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.