REST API Level for RESTful APIs

Eine REST-API kann durch Einhaltung bestimmter Regeln einem bestimmten LEVEL-Standard zugeordnet werden.

Dies ist ähnlich wie mit den NORMEN.
Wenn ein Blatt Papier die Maße 210mm x 297mm hat, entspricht dies dem DIN A4 Standard. Wenn nicht, dann halt nicht.

Wenn eine REST-API den Standard LEVEL 2 oder LEVEL 3 entsprechen soll, muss sie eben diese Eigenschaften aufweisen:

Level

L0.	Remote Procedure Call Einfacher Aufruf EINES Service-Endpunktes (die Artikel, die Mitarbeiter, die Bücher, die Zimmer...) Beispiel: /api/shop/artikel Der Aufruf erfolgt ausschließlich per GET oder POST. Alle weiteren Operationen (DELETE, PUT,...) und alle weiteren möglichen Daten beim POST werden über den BODY mitgeteilt.
L1.	Ressourcen Zeiger Eindeutige URLs direkt auf die einzelnen Ressourcen eines Services (den Artikel, den Mitarbeiter, das Buch, das Zimmer...) Beispiel /api/shop/artikel/1234 Operationen (wie PUT, DELETE) und alle weiteren Daten (Personendaten/Artikeldetails/Zimmerinformationen) werden weiterhin über den BODY an die API mitgeteilt.
L2.	Operationen über HTTP-Methoden Sämtliche Operationen wie GET, POST, PUT, DELETE, PATCH werden nicht mehr über den BODY mitgeteilt, sondern direkt über HTTP-Methoden. POST:      /api/shop/artikel GET:         /api/shop/artikel/1234 GET:         /api/shop/artikel DELETE: /api/shop/artikel/1234 PUT:         /api/shop/artikel/1234
L3.	State Machine weiterhin direkter Ressourcen Zeiger aus L1 und weiterhin Operationen über HTTP-Methoden aus L2 Hinzu kommt außerdem nun noch , dass alle Ausgaben des Servers durch Anfragen sämtliche Zustandsinformationen beinhalten. Das bedeutet, wenn z.B. einer Person mehrere Artikel zugeordnet sind, dann werden bei Abfrage nach den Persondaten zu einer Person auch alle Links zu seinen Artikeln mit aufgeführt. Und des Weiteren werden auch Links zu allen möglichen OPERATIONEN mit aufgeführt. Dadurch kann der Client komplett dynamisch anhand der Daten operieren und navigieren.

Anmerkung

Von Level 0-2 waren die Anforderungen nur auf das Senden an die API gerichtet.
Level 3 dagegen bezieht sich auf das Output der Schnittstelle.

Der LEVEL 3-Standard wird kaum vollständig genutzt. Ein guter Stil ist die Nutzung von href als Kennzeichnung von self-relations (zugehörigen Daten) - also Level 2 + gute Dokumentation (Dokumentationen siehe auch GLUE im folgenden).

Zusätzlich gute Eigenschaften zu APIs

Gute Dokumentation
Langfristig nutzbar, auf die man aufbauen kann
Unabhängig - mit mehreren Endsystemen verwendbar
Erweiterbar - durch Versionierung für künftige Erweiterungen und Anpassungen

= GLUE (engl. für Kleber der alles zusammenhält)

Für die Versionierung empfiehlt es sich, den Pfad zu ändern wie in folgendem Beispiel:
/api/v1/shop/article  ->  /api/v2/shop/article

Wenn man dann später etwas ändert, so kann im Weiteren mit V2 fortgefahren werden und die Änderung stört nicht den Betrieb älterer Systeme, die noch auf V1 zugreifen.