Lars Röwekamp OPEN KNOWLEDGE GmbH

Wichtig ist, dass man nicht versucht, das Rad neu zu erfinden, sondern auf Standards und etablierte Patterns und Best Practices zurückgreift, um so die Erwartungshaltung des Anwenders zu erfüllen.

Mehr als fünfzehn Jahre nach seiner „Erfindung“ durch Roy Fielding scheint RESTful-API-Design aktueller denn je. Egal ob im Umfeld von Microservices oder bei der Öffnung bisher nur intern genutzter Systeme – REST wohin man schaut! Aber was genau ist eigentlich REST? Nur weil JSON oder XML Payload via HTTP an einen Server gesendet beziehungsweise von eben diesem empfangen wird, hat man es noch lange nicht mit einem RESTful API zu tun. Was genau zeichnet also eine REST-Schnittstelle aus? Und ab wann kann man sie als wirklich gelungen bezeichnen? Spätestens bei dieser Frage scheiden sich die Geister.

Auf den ersten Blick scheint das Design eines RESTful API denkbar einfach. „One noun, four verbs“, so einfach kann Programmierung sein. Also kurz eine Ressource identifiziert, zusehen, dass man deren Manipulation (CRUD-Operationen) mittels Endpoint und HTTP-Methoden (POST, GET, PUT, DELETE) ermöglicht – und fertig ist das REST-API. Stellen wir uns einmal exemplarisch eine Schnittstelle vor, über die Bestellungen aufgegeben, abgefragt, geändert und gelöscht werden können (Listing 1).

 
// Create a new order via http POST and JSON payload
// representing the order to create. 
POST /api/orders 
[ ... payload representing an order ...]

// Update an existing order with id 123 via http PUT 
// and JSON payload representing the changed order. 
PUT /api/orders/123 
[ ... payload representing the changed order ...]

// Delete an existing order with id 123 via http DELETE. 
DELETE /api/orders/123 

// Retrieve an existing order with id 123 via http GET. 
GET /api/orders/123 

// Retrieve all existing orders http GET. 
GET /api/orders

Ist das wirklich schon alles? Passt die 1:1-Zurordnung von CRUD-Operationen und HTTP-Methoden tatsächlich immer? Und wie sehen eigentlich parametrisierte Ressourcenabfragen (alias Filter) zur gezielten Einschränkung der Treffermenge aus? Wie individualisiere ich das Rückgabeformat, z. B. für die Verwendung auf mobilen Endgeräten? Wie wird Security gehandhabt? Was passiert im Falle eines Fehlers? Und wie stelle ich eine mögliche Evolution des API sicher? Fragen über Fragen, aber keine Angst. Wir werden uns Schritt für Schritt mit deren Beantwortung beschäftigen.

Aller Anfang ist schwer

Das API ist das UI des Entwicklers. Ähnlich wie bei einem guten UX-/UI-Design sollte also auch beim Design eines API darauf geachtet werden, dass die Erwartungen des Anwenders – in diesem Fall also des Entwicklers – erfüllt werden. Wie aber genau sehen diese Erwartungen aus? Die gute Nachricht: Im Umfeld von REST gibt es etliche Spezifikationen, an denen man sich orientieren kann und sollte. Dies gilt zum Beispiel für die korrekte Verwendung der HTTP-Methoden und des HTTP-Statuscodes. Und findet man für eine Problemstellung keine Spezifikation, dann kann es nicht schaden, einen Blick auf bekannte und stark frequentierte APIs (Facebook, Amazon, Twitter, GIT und Co.) zu werfen und ein wenig abzugucken. In der Regel finden sich dort Patterns und Best Practices wieder, die sich im Laufe der letzten Jahre in der REST-Community etabliert haben.

Den vollständigen Artikel lesen Sie in der Ausgabe:

Entwickler Magazin Spezial Vol. 13: APIs - "APIs"

Alle Infos zum Heft
579812053Einführung ins RESTful-API-Design
X
- Gib Deinen Standort ein -
- or -