Architekturliche Einschränkungen der REST-API: Ein Leitfaden zur Gestaltung

Die sechs Einschränkungen sind Client-Server-Trennung, zustandslose Interaktionen, Cachefähigkeit, eine einheitliche Schnittstelle, ein schichtbasiertes System und optionales „Code-on-Demand“. Die ersten fünf definieren erforderliche Merkmale; das Herunterladen von ausführbarem Code ist optional. Roy Fielding entwickelt diesen Satz in Kapitel 5 seiner Dissertation.

Nutzen Sie diese Tabelle, um die Bezeichnungen in Nachweise umzuwandeln, die Sie während einer Überprüfung anfordern können. Bei den Beispielen handelt es sich um Entwurfsfragen, nicht um eine Konformitätstestsuite oder das Versprechen, dass ein einziger Header ein gesamtes System REST-konform macht.

Die Einschränkungen der REST-API-Architektur beschreiben ein System von Interaktionen. Ein Screenshot einer einzelnen Antwort kann nicht alle diese Interaktionen abbilden. Erfassen Sie einen kurzen Trace, der einen Lesevorgang, einen Übergang, einen Fehler und eine wiederholte Anfrage enthält, und untersuchen Sie dann die Annahmen, die diese Ereignisse miteinander verbinden.

Trennen Sie außerdem die Architektur von der Technologieauswahl. HTTP ist eine natürliche Umgebung für ressourcenorientierte Schnittstellen, aber ein Architekturstil ist keine Spezifikation des Übertragungsformats. Falls Ihr Team noch verschiedene Designansätze vergleicht, erklärt der Leitfaden „REST-API versus SOAP-API“, warum ein Architekturstil und ein Messaging-Protokoll unterschiedliche Bewertungskriterien erfordern.

Stellen Sie sich vor, ein Katalogdienst veröffentlicht Produktbeschreibungen und Lagerbestände. Ein Browser wählt das visuelle Layout, während ein Collector ein Speicherformat auswählt. Keiner der Nutzer muss wissen, ob der Dienst eine Datenbank abfragt oder mehrere Systeme kombiniert. Diese Trennung ist der nützliche Ausgangspunkt für das Client-Server-Design.

Verstehen Sie dies nicht als Vorgabe, für jede Ressource einen neuen Microservice zu erstellen. Eine einzelne Anwendung kann eine klare Grenze offenlegen. Umgekehrt können viele Microservices eine stark gekoppelte Schnittstelle offenlegen, wenn Aufrufer interne Datenbanknamen, die Bereitstellungsreihenfolge oder undokumentierte Workflow-Phasen kennen müssen.

Der nächste Punkt betrifft den Konversationszustand. Angenommen, ein Dienst verlangt von einem Client, zunächst ein Lager auszuwählen, und liest dann eine nicht näher spezifizierte Produktanfrage entsprechend dieser gespeicherten Auswahl. Ein Ersatzmitarbeiter kann die Anfrage nicht verstehen, indem er sie sich nur ansieht. In einem zustandslosen Design identifiziert die Anfrage das relevante Lager oder enthält anderweitig genügend Informationen, um die angeforderte Operation zu interpretieren.

Das bedeutet nicht, dass der Dienst nach jeder Antwort Produkte, Bestellungen oder Berechtigungen vergisst. Persistente Geschäftsdaten sind Ressourcenstatus. Das Problem ist der verborgene Kontext der Client-Kommunikation, der zum Verständnis einer späteren Anfrage erforderlich ist. Die Einschränkungen der REST-API-Architektur lassen sich leichter anwenden, wenn man diese beiden Arten von Status im Entwurfsdokument explizit benennt.

Die Authentifizierung erfordert die gleiche Sorgfalt. Ein Bearer-Token ist kein Beweis dafür, dass jede Interaktion zustandslos ist, und eine Datenbankabfrage während der Autorisierung ist nicht automatisch ein Beweis für das Gegenteil. Prüfen Sie, ob die Anfrage verstanden werden kann, ohne frühere Client-Interaktionen rekonstruieren zu müssen. Prüfen Sie dann die Autorisierung separat: Der Dienst muss entscheiden, ob dieser Aufrufer auf dieses bestimmte Lager und Produkt zugreifen darf.

Dokumentieren Sie bei Sammlern, welche Anfrage-Eingaben zu einem Konto, einem Standort oder einem Sammelvorgang gehören. Behalten Sie diese Eingaben bei den Arbeitselementen, wenn Sie diese zwischen den Bearbeitern verschieben. Wenn die Integration auch auf Browsersitzungen basiert, sollten Sie verstehen, wie HTTP-Cookies den Sitzungskontext bewahren, bevor Sie davon ausgehen, dass das Kopieren einer URL die Antwort reproduziert.

Angenommen, die Produktbeschreibung ändert sich nur selten, während sich die Verfügbarkeit im Laufe des Tages ändert. Beiden Antworten dasselbe lange Wiederverwendungsfenster zuzuweisen, ist zwar praktisch für die Infrastruktur, für den Verbraucher jedoch möglicherweise falsch. Die Gestaltung des Caches beginnt mit dem akzeptablen Alter der Informationen, nicht mit dem Wunsch, das Anfragevolumen zu reduzieren.

Für HTTP-APIs definiert RFC 9111 die Wiederverwendung von Cache-Inhalten und entsprechende Anweisungen. Eine Antwort kann die Speicherung untersagen, eine Validierung vor der Wiederverwendung verlangen oder die Wiederverwendung unter bestimmten Bedingungen zulassen. no-cache bedeutet nicht dasselbe wie no-store: Ersteres erlaubt die Speicherung, erfordert jedoch eine erfolgreiche Validierung vor der Wiederverwendung; Letzteres weist Caches an, die Antwort nicht zu speichern.

Ein Entity-Tag bietet einem Verbraucher einen Validator für eine ausgewählte Darstellung. Der Collector kann später If-None-Match; wenn die entsprechenden Bedingungen für einen GET erfüllt sind, erlaubt eine 304 Not Modified Antwort ermöglicht es ihm, die gespeicherte Darstellung wiederzuverwenden. Diese Antwort enthält keinen neuen Darstellungstext zum Parsen. Würde man sie als leeren Katalog behandeln, würde dies einen ansonsten funktionierenden Sammelvorgang beeinträchtigen.

Die Einschränkungen der REST-API-Architektur erfordern ein definiertes Wiederverwendungsverhalten, kein universelles Caching. Ein kontospezifischer Bericht erfordert möglicherweise eine restriktive Handhabung, während eine öffentliche Kategoriebeschreibung eine längere Gültigkeitsdauer tolerieren kann. Eine Entwurfsüberprüfung sollte beide Fälle identifizieren, anstatt für jeden Endpunkt einen Cache-Treffer zu verlangen.

Halten Sie Varianten voneinander getrennt. Wenn Sprache, Anmeldedaten, Standort oder andere Eingaben die Antwort beeinflussen, legen Sie fest, wie diese Eingaben in die Cache-Auswahl und -Richtlinien einfließen. Gehen Sie nicht davon aus, dass ein reiner URL-Cache-Schlüssel für personalisierte Daten ausreicht. Gemeinsame Caches unterliegen zudem spezifischen Einschränkungen bei authentifizierten Anfragen; überprüfen Sie daher das tatsächliche Verhalten, anstatt sich auf das Vorhandensein einer einzigen Richtlinie zu verlassen.

Speichern Sie in Ihrem Sammlungsspeicher den Abrufzeitpunkt getrennt vom vom Quellsystem bereitgestellten Änderungszeitpunkt. Sie beantworten unterschiedliche Fragen: wann Sie die Darstellung beobachtet haben und wann der Herausgeber angibt, dass sie sich geändert hat. Dies ist eine Implementierungsempfehlung zur Nachvollziehbarkeit, keine siebte REST-Einschränkung.

Die einheitliche Schnittstelle ist der Teil der REST-API-Architektur-Einschränkungen, der am leichtesten zu wenig spezifiziert wird. Sie umfasst vier Anforderungen: Ressourcen identifizieren, diese über Repräsentationen bearbeiten, Nachrichten selbstbeschreibend gestalten und Hypermedia zur Steuerung des Anwendungszustands nutzen. Bewerten Sie jede einzelne davon, anstatt „verwendet GET und POST“ als gesamte Überprüfung zu betrachten.

Eine Produktkennung bezieht sich auf die konzeptionelle Produktressource; ihr JSON-Dokument ist eine Repräsentation dieser Ressource zu einem bestimmten Zeitpunkt. Eine gerenderte Seite, ein Bild oder ein XML-Dokument können ebenfalls eine Repräsentation sein. Wenn Sie bei der Konzeption diese Unterscheidung berücksichtigen, vermeiden Sie es, das Layout einer Datenbankzeile so offenzulegen, als wäre es der dauerhafte öffentliche Vertrag.

Legen Sie für den hypothetischen Katalog fest, welche Kennung stabil bleibt, wenn sich ein Produktname ändert. Entscheiden Sie, ob Varianten separate Identitäten haben und ob nicht mehr lieferbare Produkte weiterhin adressierbar bleiben. Das sind domänenbezogene Entscheidungen. Der praktische Test besteht darin, ob Clients auf das beabsichtigte Objekt verweisen können, ohne erraten zu müssen, wie der Server es speichert.

Die Bearbeitung über Darstellungen bedeutet, dass der Client über die veröffentlichte Schnittstelle arbeitet, anstatt private Serverstrukturen direkt zu ändern. Eine übermittelte Darstellung muss dennoch vom Server validiert werden. Ein vom Client bereitgestellter Preis, eine Eigentümerkennung oder ein Berechtigungsfeld wird nicht allein dadurch maßgeblich, dass die Anfrage einen geeigneten Medientyp verwendet.

Selbstbeschreibung erfordert mehr als nur lesbare Feldnamen. Methodensemantik, Antwortstatus, Medientyp und relevante Metadaten sagen den Empfängern, wie sie mit der Nachricht umgehen sollen. Derselbe JSON-Text kann unterschiedliche Bedeutungen haben, je nachdem, ob er als erfolgreiche Repräsentation zurückgegeben oder in einer Fehlerantwort enthalten ist.

Wenden Sie bei der Verwendung von HTTP dessen tatsächliche Methodensemantik an. GET ist eine sichere Abrufmethode; PUT und DELETE sind in ihrer definierten beabsichtigten Wirkung idempotent. Idempotenz bedeutet nicht, dass bei jeder Wiederholung ein identischer Status zurückgegeben werden muss oder die Protokollierung untersagt ist. Diese Unterscheidungen ergeben sich aus der HTTP-Semantik (RFC 9110) und sind von Bedeutung, wenn eine Integration die Wiederholung eines unterbrochenen Vorgangs in Betracht zieht.

Ein Collector sollte den Status und den Medientyp prüfen, bevor er erwartete Datensätze parst. Eine erfolgreiche Netzwerkverbindung, auf die ein HTML-Gateway-Fehler folgt, ist kein gültiger JSON-Katalog. Ebenso ist ein syntaktisch gültiges JSON-Objekt mit einem Fehlerschema keine Seite, die keine Produkte enthält.

„Hypermedia as the Engine of Application State“, oft abgekürzt als HATEOAS, bedeutet, dass Clients verfügbare Übergänge aus den von der Interaktion bereitgestellten Steuerelementen auswählen. Eine Katalogdarstellung könnte einen Link zur nächsten Seite bereitstellen, dessen Beziehung eine definierte Bedeutung hat. Der Collector folgt diesem Steuerelement, anstatt jede zukünftige URL anhand einer eigenen Annahme über Offsets zu berechnen.

Fieldings Klarstellung zu hypertextgesteuerten APIs macht dies zu einer definierenden Anforderung und nicht zu einer optionalen Ergänzung. Clients müssen weiterhin den Medientyp und die Semantik der Relationen verstehen. Hypermedia macht nicht jeden unbekannten Geschäftsablauf ohne einen Vertrag verständlich.

Für eine praktische Überprüfung ändern Sie die hypothetische URL der nächsten Seite von einem Offset in einen undurchsichtigen Cursor. Ein Client, der der bereitgestellten Steuerung folgt, bleibt davon unberührt. Ein Client, der diese ignoriert und eine Zahl erhöht, ist an eine Konstruktionsregel gebunden. RFC 8288 definiert Web-Links und Relationstypen und stellt ein Vokabular für Links bereit, deren Bedeutung präziser ist als die eines beliebigen URL-Feldes.

Die Einschränkungen der REST-API-Architektur werfen daher eine tiefgreifendere Frage auf als nur die, ob Links vorhanden sind: Leiten die unterstützten Übergänge den Client tatsächlich? Das Hinzufügen eines self Links zu einer ansonsten fest programmierten Prozedur zeigt nicht die vollständige einheitliche Schnittstelle.

Ein Collector könnte ein Gateway erreichen, das zu einem Cache und anschließend zu einer Anwendung weiterleitet. Er sollte die veröffentlichte Schnittstelle nutzen, ohne davon abhängig zu sein, welche Anwendungsinstanz eine Anfrage erhält. Intern kann der Betreiber das Routing ändern oder einen Dienst ersetzen, während diese Grenze gewahrt bleibt.

Schichten sind zudem Orte, an denen Annahmen fehlschlagen können. Ein Proxy kann einen Header entfernen, ein Gateway kann eine Fehlerseite einblenden oder ein Cache kann Antworten zusammenführen, die getrennt bleiben sollten. Überprüfen Sie sowohl das End-to-End-Verhalten als auch die Konfiguration jeder einzelnen Komponente. Die Einschränkungen der REST-API-Architektur garantieren nicht, dass ein Zwischenelement korrekt konfiguriert ist.

Verwenden Sie eine kleine Trace-Matrix für den hypothetischen Katalog: direkte Anwendungsantwort, Gateway-Antwort, Cache-Revalidierung und Upstream-Timeout. Vergleichen Sie den beobachtbaren Status, die Repräsentationsmetadaten und den Fehlervertrag. Behalten Sie eine Korrelations-ID bei, die Betreibern hilft, Fehler zurückzuverfolgen, aber vermeiden Sie es, von Clients zu verlangen, interne Hostnamen oder die Bereitstellungstopologie zu verstehen.

„Code-on-Demand“ befasst sich mit einem anderen Problem: Ein Server kann das Verhalten eines Clients durch die Bereitstellung von ausführbarem Code erweitern. Ein Browser, der ein Skript lädt, veranschaulicht diesen Mechanismus. Sein optionaler Status ist von Bedeutung, da viele API-Nutzer bewusst nur Daten akzeptieren. Ein Server muss kein JavaScript an einen headless Collector senden, um die zwingenden Einschränkungen zu erfüllen.

Machen Sie bei der Datenerfassung die Ausführungsgrenze explizit. Wenn eine Seite eine Ausführung im Browser benötigt, um Daten offenzulegen, ist dies eine betriebliche Anforderung des Ziels. Dies ist kein Beweis dafür, dass jeder REST-Client beliebige Antworten ausführen muss. Ebenso bedeutet der Empfang von HTML nicht zwangsläufig, dass „Code-on-Demand“ verwendet wird; HTML-Inhalte und ausführbares Verhalten sind unterschiedliche Aspekte.

Betrachten Sie die heruntergeladene Ausführung als eigenständige Funktion mit eigenen Kontrollmechanismen. Bewahren Sie API-Anmeldedaten außerhalb von nicht damit in Zusammenhang stehenden Seitenausführungskontexten auf und legen Sie fest, welche Hosts und Navigationsziele ein browserbasierter Collector erreichen darf. Dies sind praktische Vorsichtsmaßnahmen bei der Umsetzung des Beispiels, keine neuen Ergänzungen zur Architekturdefinition.

Beginnen Sie mit einer realen Nutzerreise statt mit der Endpunktliste. Rufen Sie für das Katalogbeispiel eine Kategorie ab, folgen Sie einem Seitenwechsel, besuchen Sie ein unverändertes Produkt erneut, stoßen Sie auf eine nicht verfügbare Ressource und setzen Sie den Durchlauf nach einem Neustart des Workers fort. Erfassen Sie für jeden Schritt bereinigte Anfragen und Antworten.

Trennen Sie bei jeder Beobachtung eine nachgewiesene Eigenschaft von einer Annahme. Ein einmal erfolgreicher Neustart des Workers deutet auf die Portabilität des Kontexts hin, beweist jedoch nicht, dass es an anderer Stelle keine versteckte Sitzungsabhängigkeit gibt. Eine Steuerung zur nächsten Seite demonstriert einen angekündigten Übergang, belegt jedoch nicht, dass die gesamte Anwendung hypermediengesteuert ist.

Einschränkungen der REST-API-Architektur eignen sich am besten als Vokabular für die Überprüfung. Notieren Sie „erfordert eine undokumentierte vorherige Auswahl eines Warenlagers“ statt „schlechtes REST“. Notieren Sie „Client erstellt Paginierungs-URLs trotz einer bereitgestellten Relation“ statt „nicht modern“. Konkrete Befunde weisen auf Änderungen hin, die ein Entwickler umsetzen und ein Prüfer verifizieren kann.

Priorisieren Sie anschließend Fehler nach ihren Folgen. Eine fehlerhafte Autorisierung oder kontoübergreifendes Caching erfordern mehr Aufmerksamkeit als eine Namenskonvention. Ein Wiederholungsversuch, der Doppelarbeit verursacht, verdient eine dokumentierte Wiederherstellungsstrategie. Das Fehlen einer optionalen „Code-on-Demand“-Funktion muss nicht behoben werden, nur um das REST-Label zu erhalten.

Bei einem externen Dienst haben Sie möglicherweise keine Möglichkeit, die Schnittstelle zu ändern. Passen Sie den Collector an den dokumentierten Vertrag an, bewahren Sie den notwendigen Kontext und beschreiben Sie die Einschränkung ehrlich. Die Verwendung einer nützlichen HTTP-API, die strenge REST-Kriterien nicht erfüllt, kann dennoch eine fundierte technische Entscheidung sein. Der Fehler besteht darin, Eigenschaften anzunehmen, die die Schnittstelle nie versprochen hat.

• Überprüfen Sie die Einschränkungen der REST-API-Architektur anhand von Anforderungsverläufen und Client-Abhängigkeiten, nicht anhand des Vorhandenseins von JSON oder ansprechender Endpunktnamen.
• Trennen Sie persistente Ressourcendaten vom verborgenen Konversationsstatus und testen Sie, ob Aufgaben zwischen Verbrauchern übertragen werden können, ohne frühere Interaktionen rekonstruieren zu müssen.
• Behandeln Sie Aktualität, Validierung, Darstellungsvarianten und Fehlerbehandlung als Bestandteile des Datenvertrags, bevor Sie aggressives Caching oder Wiederholungsversuche aktivieren.
• Prüfen Sie alle vier Anforderungen an eine einheitliche Schnittstelle, einschließlich aussagekräftiger Übergänge; eine Liste von HTTP-Methoden deckt nur einen Teil des Designs ab.
• Halten Sie konkrete Integrationsbeschränkungen und deren Folgen fest, damit Korrekturen die Zuverlässigkeit und Unabhängigkeit verbessern und nicht nur die Terminologie betreffen.

Nein. Die Vorgaben schreiben keinen universellen Speicherort für die Versionsnummer vor. Eine Versionierungsrichtlinie ist eine vertragliche Entscheidung, die erklären sollte, wie Clients Änderungen erkennen und wie die Kompatibilität gewahrt wird. Bevor Sie eine Namenskonvention einführen, sollten Sie ermitteln, welche Änderungen tatsächlich bestehende Nutzer beeinträchtigen würden und wie Sie diese kommunizieren oder schrittweise einführen werden.

Nein. Ein Dienst kann intern Datenbanktransaktionen nutzen und gleichzeitig eine nach REST gestaltete Schnittstelle bereitstellen. Der Client sollte sich auf das veröffentlichte Verhalten verlassen und nicht auf die Datenbankimplementierung. Legen Sie fest, welche Konsistenz die Operation gewährleistet, was eine abgeschlossene Antwort bedeutet und wie ein Aufrufer ein ungewisses Ergebnis nach einem Verbindungsausfall untersuchen kann.

Nein. Sie legen keine Anforderungsquoten, Parallelitätsgrenzen oder ein allgemeines Warteintervall fest. Diese gehören zum Betriebsvertrag des Dienstes. Verbraucher sollten die dokumentierten Grenzen des Anbieters beachten, die Parallelität begrenzen und genügend Diagnoseinformationen aufbewahren, um Drosselung von Validierungsfehlern oder nicht verfügbarer Infrastruktur unterscheiden zu können.

Die produktivste REST-Überprüfung endet mit beobachtbaren Erkenntnissen. Sie sollten wissen, welchen Kontext eine Anfrage mit sich bringt, wann eine Antwort wiederverwendet werden kann, wie der Client sie interpretiert und woher die nächste unterstützte Aktion stammt. Sie sollten auch wissen, welche Annahmen hinter Gateways oder nach einer fehlgeschlagenen Interaktion ungeprüft bleiben.

Nutzen Sie diese Erkenntnisse, um die nächste Integration zu verbessern. Nehmen Sie eine fehlende Eingabe in den expliziten Vertrag auf, korrigieren Sie eine Cache-Grenze oder bringen Sie dem Client bei, einem vorgegebenen Übergang zu folgen. Halten Sie die Unterscheidung zwischen architektonischen Anforderungen und betrieblichen Empfehlungen sichtbar, damit das Team bewusste Kompromisse eingehen kann.

Falls Ihre Datenpipeline auch Informationen benötigt, die nur über Webseiten verfügbar sind, ziehen Sie die Scraper-API von WebScrapingAPI als separaten Erfassungseingang in Betracht. Wenden Sie dieselbe Disziplin auf diese Grenze an: Validieren Sie die Antwort, bewahren Sie den Erfassungskontext und dokumentieren Sie, welche Annahmen nachgelagerte Verbraucher hinsichtlich der zurückgegebenen Daten treffen dürfen.