APIs: der Vertrag zwischen zwei Programmen

In der letzten Lektion hast du ein System in einen Client, der fragt, und einen Server, der antwortet, aufgeteilt. In dem Moment, in dem du das tust, taucht eine neue Frage auf: Was genau schickt der Client, und was genau kommt zurück? Du und der Client seid jetzt zwei getrennte Programme, die an verschiedenen Tagen aktualisiert werden, vielleicht von verschiedenen Leuten, vielleicht in verschiedenen Jahren. Irgendetwas muss zwischen ihnen fest bleiben. Dieses Etwas ist die API.

Eine API (application programming interface) ist ein Vertrag, und es lohnt sich, dieses Wort wörtlich zu nehmen. Er besagt: Wenn du diese Anfrage schickst, bekommst du diese Antwort. Nicht "ungefähr diese", nicht "normalerweise diese". Eine Anfrage besteht aus vier Dingen: einer Methode, die sagt, um welche Art von Aktion es geht (GET liest und ändert nichts, POST erstellt, DELETE entfernt); einem Pfad, der sagt, von welcher Sache du sprichst (/orders/77); Headern, die Metadaten wie den Inhaltstyp oder ein Token mitbringen; und manchmal einem Body mit Daten. Die Antwort hat einen Statuscode und meistens einen Body mit JSON.

GET    /v1/orders/77      -> 200 OK, one order
POST   /v1/orders         -> 201 Created, the new order
DELETE /v1/orders/77      -> 204 No Content, nothing left
GET    /v1/orders/999     -> 404 Not Found, no such order
POST   /v1/orders/broken  -> 400 Bad Request, the body is wrong
GET    /v1/admin/users    -> 401 Unauthorized, no token sent

Statuscodes sind die gemeinsame Sprache für Ergebnisse, und du brauchst nur wenige Familien davon. 2xx heißt, es hat funktioniert. 4xx heißt, die Anfrage war falsch: 404 für eine Sache, die es nicht gibt, 400 für einen Body, der keinen Sinn ergibt, 401 für ein fehlendes oder schlechtes Token. 5xx heißt, der Server ist kaputtgegangen, während er eine eigentlich gültige Anfrage bearbeitet hat. Diese Aufteilung ist keine Bürokratie; sie sagt dem Client, was er als Nächstes tun soll. Ein 404 ist endgültig — nicht erneut versuchen. Ein 500 kann vorübergehend sein — ein neuer Versuch ist vernünftig. Ohne diese Aufteilung muss jeder Client raten, und jeder Client rät anders.

Eines Tages muss sich die Form einer Antwort ändern. Vielleicht war total die Zahl 12.90, und das Geschäft braucht jetzt eine Währung dazu, also wird total zu einem Objekt. Deine eigene Seite kannst du am selben Nachmittag aktualisieren; die Handy-App nicht, denn die Leute behalten alte Versionen monatelang installiert, und das Skript eines Partners wird vielleicht von jemandem aktualisiert, der noch nie von dir gehört hat. Das ist der Moment, in dem du entscheidest, ob die Änderung breaking ist. Wenn jeder bestehende Client, der seinen Code nicht ändert, jetzt scheitern wird, ist sie breaking, und sie braucht eine neue Version: /v2/orders/77 neben dem alten /v1/orders/77, und beide werden bedient, bis die alte endlich stillgelegt wird.