© Liashko/Shutterstock.com
Entwickler Magazin
Einführung ins RESTful-API-Design

Pragmatisch, praktisch, gut

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.

Lars Röwekamp


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).

Listing 1: CRUD-Operationen via REST// 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-Zuordnung 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.

...

Entwickler Magazin
Einführung ins RESTful-API-Design

Pragmatisch, praktisch, gut

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.

Lars Röwekamp


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).

Listing 1: CRUD-Operationen via REST// 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-Zuordnung 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.

...

Neugierig geworden?


   
Loading...

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang