REST-APIs müssen hypertextgesteuert sein
De Roy Fielding's Blog Hier finden Sie eine Reihe von Möglichkeiten, um zu prüfen, ob Sie eine HTTP-API oder eine REST-API erstellen:
API-Designer, beachten Sie bitte die folgenden Regeln, bevor Sie Ihre Kreation eine REST-API nennen:
- Eine REST-API sollte nicht von einem einzigen Kommunikationsprotokoll abhängig sein, auch wenn ihre erfolgreiche Abbildung auf ein bestimmtes Protokoll von der Verfügbarkeit von Metadaten, der Wahl der Methoden usw. abhängen kann. Im Allgemeinen muss jedes Protokollelement, das einen URI zur Identifizierung verwendet, die Verwendung eines beliebigen URI-Schemas für diese Identifizierung zulassen. [Ein Versagen hier bedeutet, dass die Identifizierung nicht von der Interaktion getrennt ist.]
- Eine REST-API sollte keine Änderungen an den Kommunikationsprotokollen enthalten, abgesehen vom Ausfüllen oder Korrigieren der Details nicht spezifizierter Teile von Standardprotokollen, wie der PATCH-Methode von HTTP oder dem Link-Header-Feld. Workarounds für fehlerhafte Implementierungen (wie z.B. jene Browser, die dumm genug sind zu glauben, dass HTML den Methodensatz von HTTP definiert) sollten separat oder zumindest in Anhängen definiert werden, in der Erwartung, dass der Workaround irgendwann veraltet sein wird. [Das Scheitern hier impliziert, dass die Ressourcenschnittstellen objektspezifisch und nicht generisch sind.]
- Eine REST-API sollte fast den gesamten Beschreibungsaufwand auf die Definition des Medientyps bzw. der Medientypen verwenden, die für die Darstellung von Ressourcen und die Steuerung des Anwendungsstatus verwendet werden, oder auf die Definition von erweiterten Beziehungsnamen und/oder hypertextfähigem Markup für bestehende Standardmedientypen. Jeglicher Aufwand für die Beschreibung, welche Methoden für welche URIs von Interesse zu verwenden sind, sollte vollständig im Rahmen der Verarbeitungsregeln für einen Medientyp definiert werden (und in den meisten Fällen bereits durch bestehende Medientypen definiert sein). [Ein Scheitern hier impliziert, dass Out-of-Band-Informationen die Interaktion steuern und nicht der Hypertext.]
- Eine REST-API darf keine festen Ressourcennamen oder Hierarchien definieren (eine offensichtliche Kopplung von Client und Server). Die Server müssen die Freiheit haben, ihren eigenen Namensraum zu kontrollieren. Stattdessen sollten die Server den Clients Anweisungen für die Erstellung geeigneter URIs geben, wie dies in HTML-Formularen und URI-Vorlagen geschieht, indem sie diese Anweisungen in Medientypen und Link-Relationen definieren. [Ein Scheitern bedeutet hier, dass die Clients eine Ressourcenstruktur aufgrund von Informationen außerhalb des Bandes annehmen, wie z. B. einen domänenspezifischen Standard, der das datenorientierte Äquivalent zur funktionalen Kopplung von RPC ist.]
- Eine REST-API sollte niemals "typisierte" Ressourcen haben, die für den Client von Bedeutung sind. Autoren von Spezifikationen können Ressourcentypen zur Beschreibung der Serverimplementierung hinter der Schnittstelle verwenden, aber diese Typen müssen irrelevant und für den Client unsichtbar sein. Die einzigen Typen, die für einen Client von Bedeutung sind, sind der Medientyp der aktuellen Darstellung und standardisierte Beziehungsnamen. [dito]
- Der Einstieg in eine REST-API sollte ohne Vorkenntnisse erfolgen, abgesehen vom anfänglichen URI (Lesezeichen) und einer Reihe von standardisierten Medientypen, die für die vorgesehene Zielgruppe geeignet sind (d. h. von denen erwartet wird, dass sie von jedem Client, der die API verwenden könnte, verstanden werden). Von diesem Zeitpunkt an müssen alle Zustandsübergänge der Anwendung durch die Auswahl des Clients aus den vom Server bereitgestellten Auswahlmöglichkeiten gesteuert werden, die in den empfangenen Darstellungen enthalten sind oder durch die Manipulation dieser Darstellungen durch den Benutzer impliziert werden. Die Übergänge können durch das Wissen des Clients über Medientypen und Ressourcenkommunikationsmechanismen bestimmt (oder begrenzt) werden, die beide on-the-fly verbessert werden können (z. B. Code-on-demand). [Ein Versagen impliziert hier, dass die Interaktion durch Out-of-Band-Informationen und nicht durch Hypertext gesteuert wird.]