© StanislauV/Shutterstock.com
Anleitung für bessere REST-Schnittstellen

RESTful APIs richtig gemacht


Wer schon einmal eine Domäne mit Microservices aufgebaut hat, wird es bereits wissen: APIs für die Service-zu-Service-Kommunikation sind von zentraler Bedeutung. Da jedes Team seinen eigenen Stil hat und Schnittstellen jeweils anders implementiert, kommt es über kurz oder lang zu einem Wildwuchs von verschiedenen Ansätzen. Gleich zu Projektbeginn einen Leitfaden mit Richtlinien und Beispielen zu definieren, hilft, einheitliche und möglichst selbsterklärende APIs zu gewährleisten.

REST mit JSON ist der heute am weitesten verbreitete Ansatz für neue Programmierschnittstellen. Unzählige Bücher, Vorträge, Blogs und andere Quellen im Internet beschäftigen sich mit dem Thema. Trotzdem scheint es große Auffassungsunterschiede in der Entwicklergemeinde zu geben, wie Webschnittstellen auszusehen haben. Die JSON-API-Spezifikation [1] legt genau fest, wie ein RESTful API basierend auf einem einheitlichen Standard implementiert werden sollte.

Zunächst aber noch ein paar Worte zu APIs. Bei der Definition eines API sollte sich der Entwickler genug Zeit nehmen, denn gut entworfene APIs führen automatisch zu besseren Produkten. Es empfiehlt sich, zu Beginn eines Projekts Richtlinien zu entwickeln, die die zentralen Anforderungen an ein API festhalten. Mithilfe von Schlüsselwörtern laut RFC 2119 [2] lässt sich festlegen, wie wichtig (oder zwingend) eine einzelne Anforderung ist. Themen für einen Richtlinienkatalog sind beispielsweise API-Namensgebung, HTTP-Header und Operationen, Anfrageparameter oder Dokumentstruktur.

Richtlinien für den API-Entwurf helfen, ein gemeinsames Verständnis zu entwickeln. Grundsätzlich lässt sich sagen, dass Services, die einheitliche Standards verfolgen, leichter zu verstehen und einfacher zu integrieren sind. Daneben lassen sie sich effizienter umsetzen (gemeinsame Tools), sind stabiler gegenüber Änderungen und einfacher zu warten.

Styleguide für JSON-APIs

In der JSON-API-Spezifikation finden sich konkrete Vorschläge, wie ein gut entworfenes REST-API aussehen kann. Aus unserer Sicht ist die Spezifikation ein guter Einstiegspunkt ins Thema. Für unsere Beispiele begeben wir uns gedanklich in die Welt der Sportvereine. Wir wollen mit unserer gedachten IT-Lösung Teams, Manager und Spieler verwalten.

spiegl_geiler_apis_1.tif_fmt1.jpgAbb. 1: Datenmodell

Das Diagramm (Abb. 1) zeigt die Entität Team und seine Beziehungen. Ein Team wird von einem Manager trainiert. Einem Team werden mehrere Spieler (Player) zugeordnet. Manager und Player sind jeweils vom Typ Person.

Manager oder C...

Exklusives Abo-Special

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