Die meisten RESTful APIs sind in Wirklichkeit nicht RESTful

(florian-kraemer.net)

24 Punkte von GN⁺ 2025-07-10 | 1 Kommentare | Auf WhatsApp teilen

In Roy Fieldings ursprünglicher REST-Abhandlung werden weder die Nutzung von HTTP-Methoden noch CRUD-zentrierte APIs eindeutig vorgeschrieben; stattdessen betont REST ursprünglich den Entwurf hypermedienbasierter (HATEOAS) Systeme
Viele Dinge, die als RESTful API bezeichnet werden, implementieren wichtige REST-Einschränkungen nicht, insbesondere die Nutzung von Hypermedia
Ressourcen sind nicht auf einfache Datenstrukturen oder Entitäten beschränkt, sondern umfassen jedes Konzept, das per URI identifizierbar ist
Laut Fieldings sechs Regeln sind hypermedienzentrierte Navigation, Protokollunabhängigkeit und die Betonung von Medientypen zentral
In der Praxis werden die meisten APIs wegen der Bequemlichkeit von Dokumentationstools wie OpenAPI eher im RPC-Stil als wirklich RESTful entworfen

Warum die meisten RESTful APIs nicht wirklich RESTful sind

Roy Fieldings maßgebliche Abhandlung (2000) stellt REST (Representational State Transfer) als idealen Stil für den Entwurf netzwerkbasierter Software vor und erklärt ihn als Prinzip hinter dem Erfolg des Webs
Die Abhandlung schreibt die Verwendung von HTTP-Methoden oder ein CRUD-zentriertes Design nicht zwingend vor; stattdessen betont sie für REST hypermedienbasierte (HATEOAS) Zustandsübergänge, eine einheitliche Schnittstelle und ressourcenzentrierte Interaktionen

Hypermedia (HATEOAS) und Missverständnisse über REST

Fielding weist ausdrücklich darauf hin, dass APIs ohne Hypermedia nicht RESTful sind
- „Wenn die Engine nicht durch Hypertext angetrieben wird, ist sie nicht RESTful“
HATEOAS bedeutet, dass der Client sein Verhalten dynamisch entdeckt, indem er in Serverantworten eingebetteten Links folgt
Nur eine HTTP-/CRUD-Schnittstelle zu verwenden, entspricht nicht dem eigentlichen Wesen von REST

Häufige Missverständnisse über REST

Die Vorstellung, REST sei gleich CRUD (tatsächlich ist es ein viel breiteres Konzept)
Das Missverständnis, Ressourcen seien Entitäten, also Datenstrukturen auf dem Server
Die Behauptung, in einer RESTful API dürften keine Verben verwendet werden
All das sind lediglich Designentscheidungen und nicht unmittelbar mit dem Wesen von REST verbunden

Die tatsächliche Bedeutung von hypermediengesteuertem Verhalten (HATEOAS)

Der Zweck von HATEOAS besteht darin, die Kopplung zwischen Client und Server zu minimieren
Wenn sich die URI-Struktur des Servers ändert, verringert sich der Aufwand für eine erneute Bereitstellung des Clients, was Skalierbarkeit und Weiterentwicklungsfähigkeit erhöht

Der Client entdeckt sein Verhalten, indem er Hyperlinks in der Antwort folgt, ohne Dokumentation oder Vorwissen

{  
  "orderId": 123,  
  "_links": {  
    "self": { "href": "/orders/123" },  
    "cancel": { "href": "/orders/123/cancel", "method": "POST" }  
  }  
}

Wie oben gezeigt, kommt man echtem RESTful näher, wenn die Antwort Aktionen (Links) enthält

Was ist eine Ressource in REST?

Eine Ressource ist alles, was per URI identifizierbar ist
- Dazu gehören Dokumente, Bilder, physische Objekte, Dienste, abstrakte Konzepte usw.
Auf dem Server existiert nicht zwingend eine tatsächliche „Ressource“, sondern lediglich eine abstrakte Zuordnungsstruktur, auf die per URI zugegriffen werden kann
Auch RFC 3986 begrenzt den Umfang von Ressourcen nicht
- Dazu können elektronische Dokumente, Bilder, Informationsquellen, Dienste und sogar Personen, juristische Personen oder Bücher gehören

Die 6 Regeln für eine RESTful API nach Fielding

1. Nicht an ein einzelnes Protokoll gebunden sein
- URI-basierte Identifikation muss über alle Protokolle hinweg nutzbar sein
2. Protokollstandards (z. B. HTTP) nicht willkürlich verändern
- Defizite in Standards dürfen ergänzt werden, aber willkürliche zusätzliche oder geänderte Regeln sind unzulässig
3. Sich auf Medientypen (Formate) statt auf URI-Strukturen konzentrieren
- Fokus auf Datenformat und Linkdefinitionen, keine Energieverschwendung für Pfadspezifikationen oder deren Dokumentation
4. Keine feste URI-Benennung oder Hierarchie hart codieren
- Der Client soll die Namespace-Struktur des Servers weder erraten noch fest verdrahten, sondern per Links navigieren
5. Ressourcentypen (interne Klassifizierung) nicht offenlegen
- Interne Objekttypen sind für den Client bedeutungslos; offengelegt werden sollten nur standardisierte Medientypen und Links
6. Nur ein Lesezeichen (Start-URI) ist nötig, alles Weitere wird über Links in Antworten entdeckt
- Der Client kennt nur standardisierte Medientypen, und Zustandsübergänge müssen stets auf Hyperlinks in Serverantworten basieren

Interpretation der Regeln und praktische Anwendung

Um echtem RESTful nahezukommen, muss die Kopplung an Protokoll, URI und Typen minimiert werden
APIs sollten sich auf das Format von Daten und Links (Medientypen) konzentrieren; URI-Strukturen oder Benennungsregeln muss der Client nicht im Voraus kennen
Statt etwa einen Pfad wie /users/123/activate zu spezifizieren, sollte die Antwort die Aktion über einen "activate"-Link anleiten

Warum echte RESTful APIs selten sind

Die Bequemlichkeit von Tools wie OpenAPI und Swagger wird in der Praxis bevorzugt
- Sie bieten greifbare Vorteile wie automatische Dokumentation, Codegenerierung und Validierung
In SPA-Umgebungen, in denen Client und Server vom selben Team entwickelt werden, ist der Bedarf, URI-Kopplung zu vermeiden, oft gering, weshalb die Vorteile von HATEOAS weniger hervorstechen
Die anfängliche Lernkurve der REST-Prinzipien und die Komplexität des Parsens dynamischer Links sind weitere praktische Hürden

Fazit

Nach Fieldings Regeln sind für eine wirklich RESTful API hypermedienbasierte (HATEOAS) dynamische Navigation und Zustandsübergänge unverzichtbar
REST bedeutet nicht einfach, CRUD über HTTP zu implementieren, sondern ist eine Architektur, die sich – wie das Web selbst – auf lose Kopplung, Weiterentwicklungsfähigkeit und dynamische Zustandsübergänge konzentriert
In der Praxis können Zweckmäßigkeit und die konkrete Teamsituation wichtiger sein
- Für öffentliche APIs für externe Entwickler ist der Einsatz von HATEOAS empfehlenswert, für rein interne APIs kann ein einfacher RPC-Stil praktischer sein
Entscheidend ist, APIs so zu entwerfen, dass sie leicht zu erlernen und schwer falsch zu verwenden sind; sie müssen nicht zwingend RESTful sein

1 Kommentare

GN⁺ 2025-07-10

Hacker-News-Kommentare

Ich kann den übertriebenen Purismus hier nachvollziehen und fand auch Fieldings Dissertation interessant, aber für mich ist das ein längst beendeter Krieg. Sobald ich den Begriff REST API höre, kann ich fast sicher sein, dass Folgendes gemeint ist:
- Die API gibt JSON zurück
- CRUD-Operationen sind auf POST/GET/PUT/DELETE abgebildet
- Das Team streitet endlos über passende HTTP-Statuscodes, und einige Codes werden anders als in der Spezifikation verwendet
- Es besteht sogar die Möglichkeit, dass ein Listing-Endpoint zur Unterstützung komplexer Filter auf POST umgestellt wird Wie bei Agile, CI oder DevOps kann man entweder stur an der ursprünglichen Definition festhalten, oder akzeptieren, dass sich die gesellschaftliche Bedeutung längst verändert hat, und den Begriff einfach so verwenden, wie er heute üblich ist
- Ich denke, Fielding hat gerade deshalb gewonnen, weil seine Logik widersprüchlich war und größtenteils falsch lag. Es ist das Paradigma von "worse is better" im 21. Jahrhundert. RPC-Systeme waren schlecht benutzbar und konnten sich nicht durchsetzen, etwa Sun RPC, RMI, DCOM, CORBA, XML-RPC, SOAP oder Protocol Buffers. Die Leute sagen zwar, REST sei kein RPC, aber in Wirklichkeit baut man in Javascript am Ende doch so etwas wie
```
const getItem = async (itemId) => { ... }
```
Diese Funktion ruft dann
```
GET /item/{item_id}
```
auf. Im Backend gibt es dann eine Funktion wie
```
Item getItem(String itemId) { ... }
```
und per Annotation wird das URL-Mapping beschrieben. Am Ende ist das RPC. Nur bleibt es statt in einem komplexen und unintuitiven System in einer handwerklicheren Form, die Entwickler besser kontrollieren können. 80 % der Probleme entstehen ohnehin nur dadurch, dass Leute kein ISO-8601-Datumsformat verwenden
- Ich verstehe nicht so recht, warum irgendjemand das als "Kampf" ansieht oder sich so darum schert. Das REST-Konzept ist nützlich, aber der HATEOAS-Teil ist kaum praktisch und verursacht nur Probleme. Im Richardson maturity model ist der höchste Reifegrad von REST an Elemente wie HATEOAS gebunden. Ich verstehe auch die Logik nicht, dass es ohne HATEOAS nicht mehr REST sein soll, denn das ist kein besonders großer Unterschied. Wenn HATEOAS in der Praxis fast bedeutungslos ist, wirkt diese prinzipienfixierte Kategorisierung ziemlich sinnlos. Richardson maturity model
- Zum Punkt "Teams diskutieren übertrieben viel über Statuscodes und verwenden sie oft entgegen der HTTP-Spezifikation": Es sollte klar sein, dass 401 Unauthorized für nicht authentifizierte Fälle und 403 Forbidden für fehlende Berechtigungen verwendet werden sollte
- Ich frage Leute meist, ob sie mit REST wirklich das meinen, was in der Dissertation definiert ist. Normalerweise gehöre ich eher zu denen, die den Missbrauch bedeutungsloser Begriffe nicht einfach hinnehmen. Am Ende denke ich mir dann aber doch nur: "Ach so, du meinst einfach eine Web-API." Wichtiger ist, dass man bei jeder solchen API ihre jeweiligen Merkwürdigkeiten erkennen muss
- Für mich ist die wirklich wichtige Nuance, dass "Hypermedia-Links" mit verschiedenen link types, die etwa in HTTP-Headern oder Rückgaben enthalten sind, zwar irgendwie "allgemein" wirken, heutige REST-Systeme aber praktisch genauso funktionieren. Wenn man zum Beispiel etwas schlecht designt hat und es statt "activate" eigentlich "enable" heißen sollte, muss man am Ende eben doch von /api/v1/account/ID/activate auf /api/v2/account/ID/enable wechseln. Das heißt: Man muss die Bedeutung aller Aktionen in einer API irgendwo fest einkodieren, und zusätzlich fehlen oft Metadaten wie Icons oder Übersetzungen von Aktionsbeschreibungen. Diese vermeintliche "Allgemeingültigkeit" ist in Wahrheit eine Illusion
Als ich vor 13 Jahren zum ersten Mal eine HTTP-API entwickeln musste, habe ich Fieldings Dissertation von vorne bis hinten gelesen, um herauszufinden, was echtes REST überhaupt ist, und außerdem RESTful Web Services Cookbook gelesen. Dann habe ich unter Umgehung der Django-Konventionen eine REST-API gebaut. Das war eine Art Cargo-Cult-Ansatz, denn ich wusste gar nicht wirklich, welchen Vorteil echtes REST unserem Dienst bringen sollte. Erst nachdem ich einige Jahre lang verschiedenste HTTP-APIs gebaut hatte, wurde mir klar, dass mir die REST-Lehre in der Praxis keinerlei Vorteile bringt. Die Vision von "Self-Discovery" und "Kompatibilität mit generischen Clients" ist fast unmöglich umzusetzen, und konkret liefert Fieldings Dissertation dafür nicht einmal wirklich eine vollständige Anleitung. Um eine tatsächlich selbstentdeckbare API zu bauen, bräuchte man konkrete Regeln für "Endpoint-Discovery-Protokolle", "Operationsbeschreibungen", "Hilfemeldungen" und Ähnliches. Und am Ende müsste man sowieso einen spezialisierten Client bauen, der genau diese Regeln versteht, womit der Vorteil eines generalisierten Clients wieder verschwindet. In der Realität blieb daher nur, für jeden Server jeweils angepassten API-/JS-/CLI-Code zu schreiben. Dazu kommt, dass gute UX mit dem REST-Ideal kollidiert, denn wirklich gute UX entsteht meist erst durch anwendungsspezifischen Code im Frontend. Man kann UI-Elemente zwar standardisieren, aber in der Praxis ist es viel nützlicher, mit einer Sprache wie JavaScript flexible UIs zu bauen
- Ich teile die Einschätzung zu den Grenzen des Konzepts einer selbstentdeckbaren API. Ein echter REST-Client ist praktisch nicht implementierbar. Er müsste das Verhalten jeder URL kennen, und wenn ein neues Verhalten hinzukommt, etwa /cansofspam/123/frobnicate, kann der Client damit nicht klar umgehen. Dann braucht er entweder ein Update, ignoriert es oder kann höchstens einen sehr simplen Button wie Frobnicate ergänzen. Deshalb gibt es in der Praxis weder vollständig REST-konforme Server noch Clients. Realistisch betreibt man APIs so, dass Clients einfach genau die erwartete API ohne Discovery unterstützen
- APIs haben viele verschiedene Aspekte, deshalb ist ihre Beschreibung schwierig. API-Nutzer müssen auch Dinge wie durchschnittliche Antwortlatenz, retry-fähige Fehlercodes oder Atomarität/Idempotenz von Aktionen kennen. Mit HATEOAS allein lässt sich so etwas nicht ausdrücken. Man muss perfektes REST nicht umsetzen, und der eigentliche Grundnutzen von REST ist letztlich nur, dass es eine gemeinsame Sprache gibt, in der Nomen und Verben auf HTTP-Methoden und URLs abgebildet werden. Trotzdem steckt in den Details enorm viel Design- und Abwägungsaufwand. Zum Beispiel gibt es Dinge, die laut HTTP-Spezifikation erlaubt sind, sich aber hinter einem realen LB nicht verwenden lassen, oder Fragen dazu, wann 500-Fehler erneut versucht werden sollen und welche Backoff-Logik dafür sinnvoll ist
- Der Browser ist eigentlich genau dieser "generische Code" und liefert uns jeden Tag die beste UX. Im REST-Konzept ist sogar enthalten, dass der Server dem Client Code übergeben kann. Es gibt dabei zwar Sicherheitsprobleme, aber Browser und Standards haben vieles davon bereits gelöst. Relevanter Abschnitt in Fieldings Dissertation
- Tatsächlich bringt selbst eine abgeschwächte Definition von REST nicht besonders viel. Dass man für das Löschen einer Ressource unbedingt DELETE verwenden müsse, ist nicht so wichtig. Wenn man stattdessen einfach POST nimmt, wem macht das wirklich Schwierigkeiten?
- Ich habe nie gedacht, dass "selbstentdeckbar" überhaupt das Ziel sei, und ich halte es auch nicht für etwas, das erreichbar wäre. Für einfache Client-Designs ist diese Erwartung von vornherein überzogen. Vor allem taucht das Wort "discoverable" im TFA überhaupt nicht auf
Diese Art von API-Design ist dort wirklich sinnvoll, wo Nutzer und Agenten, die stellvertretend für sie navigieren, etwa Browser, die API erkunden und anhand von Medientypen und Link-Informationen in den Antworten interagieren können. Die meisten Web-APIs sind nicht für so einen Use Case gedacht, sondern für Web-Apps mit gezielt gestalteter UI/UX. Das ist eine bewusste Entscheidung. App-Entwickler wollen Darstellung der Daten, UI-Fluss und Ähnliches vollständig kontrollieren, um ihre Produktziele zu erreichen. REST-API-Design wird dort wichtig, wo Nutzer die Verwendung der API-Ressourcen stärker selbst steuern sollen. Beispiele wären
- frei zugängliche staatliche Informationsportale, etwa zu Gesetzen, Wetter oder Grundbucheinträgen
- staatliche Portale, bei denen verschiedenste Formulare eingereicht werden müssen
- Open-Data-Projekte wie Wikipedia oder OpenStreetMap In solchen Bereichen sollte man REST-API-Design einsetzen. Letztlich haben Menschen, die strikt auf der REST-Definition bestehen, oft eher einen akademischen Hintergrund, während diejenigen, die den Begriff weiter fassen, meist Entwickler sind, denen die App-Erfahrung wichtiger ist. Die Lösung ist einfach: Wenn es kein echtes REST ist, sollte man es nicht REST nennen
- HTML-Dokumente sind genau genommen tatsächlich dieses Beispiel. Im Dokument gibt es Links zu anderen Dokumenten, und Nutzer können anhand des Linktexts frei navigieren. Wenn es für Menschen gedacht ist, nennt man es UI, und wenn es für Anwendungen gedacht ist, nennt man es API. HATEOAS wirkt nur deshalb so seltsam, weil es aussieht, als wolle man APIs direkt auf Nutzer ausrichten. Aber genau das haben wir mit UI ja bereits
- Das reine REST-Konzept ist sehr akademisch. Wenn man in Open-Data- oder Big-Data-Projekten reale Performance oder Architektur umsetzen will, ist ein pragmatischer Ansatz wichtiger als die Frage, ob man REST vollständig erreicht hat. Selbst Akademiker beharren am Ende nicht nur auf perfektem REST, weil sie schließlich auch funktionierende Ergebnisse liefern müssen
- Diese Art von API-Design ist nicht nur für Webseiten nützlich, sondern auch beim Bau anderer Clients. Man kann per GET Ressourcen abrufen, Werte über Felder oder Pfade extrahieren und daraus neue URIs konstruieren, um Aktionen auszuführen. So lassen sich verschiedenste Apps, CLIs oder UIs nach ähnlichen Mustern bauen. In einer non-SPA ließe sich das sogar direkt mit HTML umsetzen. Letztlich dereferenziert der Nutzer oder user-agent Informationen innerhalb der zurückgegebenen Repräsentation
- Ich frage mich, ob dieser Use Case wichtiger wird, wenn AI beginnt, APIs zu konsumieren. Die Discoverability von APIs ist für AI viel wertvoller als für Web-App-Entwickler. Am MCP (Model Context Protocol) sieht man, wie mächtig Tool-Discoverability sein kann. HATEOAS könnte auch für diesen direkten Konsum von Bare APIs erhebliche potenzielle Vorteile haben
- Wenn öffentliche Informations-APIs gut entworfen sind, wie etwa die RESTful-Service-API-Dokumentation des US-Wetterdienstes, ist das wirklich angenehm
Zu dem Punkt, dass sich die anfängliche kognitive Belastung beim Bauen eines wirklich hypermedienbasierten Clients riesig anfühlte und es viel einfacher schien, einfach URI-Templates wie /users/{id}/orders fest einzukodieren: Genau das habe ich empirisch auch so erlebt. Die reine REST-Lehre bietet in den meisten Fällen ein schlechtes Kosten-Nutzen-Verhältnis. Das ist ein bisschen so, als würde man bei einer Mikrowelle mit nur einem Knopf Menü, Betriebsart und Zeit zugleich steuern müssen, statt einfach vertraute Standardknöpfe zu nutzen. Selbst mein OBD-Lesegerät mit zwei Tasten ist absurd umständlich zu bedienen. Dass immer noch die Kultur existiert, man müsse unbedingt Fieldings Dissertation lesen, ist ziemlich fragwürdig. Wenn eine Idee gut ist, sollte sie sich auf verschiedene Arten und aus einer populäreren Perspektive leicht erklären lassen. Niemand sagt schließlich, man müsse Newtons Principia lesen, um Physik zu verstehen
Damit RESTful-/HATEOAS-Muster wirklich einen Wert haben, braucht es Clients, die sie verstehen. htmx: hypermedia clients intercoolerjs: hatoeas-is-for-humans
UI-Designer wollen die konkreten Details des Erscheinungsbilds eines Bildschirms kontrollieren. Manche für eine Ressource möglichen Aktionen sollen als große Buttons erscheinen, andere im Menü versteckt sein oder gar nicht im UI auftauchen. Wenn Aktionen je nach Zustand dynamisch auf Basis der API-Antwort gerendert werden, sehen am Ende alle Aktionen gleich aus. Deshalb halte ich RESTful APIs für ungeeignet zur Umsetzung typischer Web-Frontend-UIs
- Diese Behauptung enthält mehrere Fehler
  1. UX-Designer sind über den gesamten Produktentwicklungszyklus hinweg beteiligt und haben nicht automatisch immer vollständige Kontrolle. Die Platzierung einer bestimmten Aktion im UI ist etwas anderes als der "state" einer Aktion. Wenn der Zustand etwas einschränkt, muss sich auch UX an diese Einschränkung halten
  2. Architektonisch kann es sogar besser sein, Zustandsprüfungen zu kapseln, sodass if (resource.links['action'] !== null) oft sinnvoller ist als if (state === something). Die meisten Zustandsänderungen müssen ohnehin auf dem Server validiert werden, und wenn man das nur dort implementiert, wird das Frontend weniger komplex. Ich habe ziemlich lange HATEOAS-Anwendungen entwickelt und betreue auch HAL4J. Es gibt Komplexität, aber UI-Design an sich ist keine Einstiegshürde
- Meiner Erfahrung nach hatte die Entwicklung von "RESTful APIs" nur selten eine direkte Verbindung zur UI. Wenn man nur eine echte UI braucht, ist die API selbst oft überflüssig; dann kann man auch einfach servergesteuerte Ansätze verwenden, etwa früher mit DWR
Ich verstehe nicht, warum HATEOAS, das in der Realität fast nie verwendet zu werden scheint, immer noch so intensiv diskutiert wird. Mich würde wirklich interessieren, ob es Orte gibt, die das tatsächlich einsetzen, und welche "automatisch navigierenden Clients" es gibt, die die Serverinformationen nicht schon vorher kennen müssen
- Zur Erinnerung: ACME, also das Protokoll von Let’s Encrypt, basiert auf HATEOAS. Es wird damit faktisch in den meisten HTTPS-Diensten verwendet. Auch HTTP selbst ist, richtig eingesetzt, ursprünglich ein HATEOAS-Protokoll. "Auto-Discovery" bedeutet hier, dass man Ressourcen über Linktypen oder Dinge wie next erkunden kann. Der Client muss die Bedeutung von next natürlich vorher kennen. LLMs sind für so eine automatische Navigation ebenfalls stark
- Ich habe HATEOAS in einem Videoüberwachungssystem auf Enterprise-Niveau eingesetzt. Versions- und Berechtigungsprobleme ließen sich damit auf API-Ebene hervorragend lösen. Wir haben auch mehrere RFCs mitgenutzt. Das größte Problem war allerdings, dass Leute aus "Bequemlichkeit" heraus immer wieder das Modell aufbrechen wollten und dadurch erst recht Komplexität erzeugten. Außerdem ist JSON seinem Wesen nach kein Hypertext-Format, sodass es oft gezwungen wirkte, HATEOAS in application/json hineinzupressen
- Du benutzt HATEOAS gerade, um einen Kommentar einzugeben, und antwortest in genau diesem Moment darauf. Der "magische automatisch navigierende Client", der das ermöglicht, ist schlicht der Webbrowser
- htmx ist vielleicht der realistischste Versuch
- Standards wie OData werden ebenfalls kaum genutzt und sind selbst dann nicht besonders populär. HATEOAS hat noch weniger Popularität und Standardisierung, daher verbreitet es sich wohl erst recht nicht
Was in dieser Diskussion leicht übersehen wird, ist die Art der Backend-API-Konsumenten. REST und HATEOAS sind meist dann sinnvoll, wenn Dritte die API nutzen, ohne das Backend direkt selbst zu besitzen. Das Endprodukt klassischer HTML-Seiten wird zum Beispiel letztlich vom Browsernutzer konsumiert. Auch aktuelles MCP ist entstanden, weil es Fälle gibt, in denen verschiedene JSON-RPC-APIs entdeckt und interpretiert werden müssen. Wenn Frontend und Backend dagegen 1:1 aufeinander abgestimmt sind, ist der Nutzen von REST im Verhältnis zu den Kosten oft gering. Dann müsste man deutlich generischer dokumentieren und spezifizieren, während in der Praxis Werkzeuge, die Separation of Concerns zugunsten höherer Produktivität bewusst missachten, wie trPC, oft hilfreicher sind. Für Prototypen ist eine End-to-End-Integration schneller
- Stimme ich sehr zu, und ich empfehle die Texte HATOEAS is for humans und htmx: hypermedia clients
- *HATEOAS
Zu der Behauptung, mit HATEOAS und Schema-Referenzen wie XSD oder JSON Schema seien dynamisch navigierende Clients möglich: In der Praxis wiederholen Funktionen wie additionalProperties in JSON Schema eher das Grundproblem. Ich halte es für robuster, Dokumentation "out of band" bereitzustellen. Wenn man dann aber einfach nur einen Swagger-Dokumentationslink in _links hinterlegt und der Client daraus den self path ableitet, wozu braucht man _links dann überhaupt noch? Wenn es ohnehin Clients gibt, die so komplexe JSON-Dokumente verarbeiten können, dann liefern Swagger-Templates und Ähnliches viel mehr Informationsdichte und Dynamik. Mit bloßen CRUD-Links lässt sich eine API insgesamt nicht ausreichend beschreiben, und auch mit JSON Schema kann man unmöglich alles abdecken
Wenn man es einfach HTTP-API nennt, sind alle glücklicher. REST war ursprünglich ohnehin nicht für APIs gedacht. Von Anfang an war REST für Informationssysteme gedacht, die von Menschen konsumiert werden, nicht von Programmen