Die Kladde hat seit Modul 2.3 eine API. Sie liefert Kontakte und Termine, kennt Statuscodes, beschreibt sich in einem OpenAPI-Dokument und liefert Kontakte in Seiten (Lektion 2.3.10). Mit Modul 2.12 kommen Aufrufer dazu, die nicht Sie selbst sind: ein anderes Programm, ein Partner, später ein Gateway. Für sie zählt mehr als „es funktioniert“. Eine Liste darf beim Blättern keinen Termin verschlucken, zwei Personen dürfen sich nicht gegenseitig die Änderungen überschreiben, und eine Buchung, die wegen eines Netzfehlers zweimal ankommt, darf nur einmal gebucht werden. In dieser Lektion schneiden Sie die Termin-API so, dass genau das gilt.

Ressourcen statt Verben

Eine REST-API beschreibt Dinge, nicht Handlungen. Die Handlung steckt in der Methode:

Statt Besser Warum
POST /api/createAppointment POST /api/appointments die Methode sagt „anlegen“
GET /api/getAppointment?id=7 GET /api/appointments/7 ein Einzelstück hat eine eigene Adresse
POST /api/appointments/7/delete DELETE /api/appointments/7 DELETE ist idempotent, ein POST nicht

Zwei Formen tragen fast jede API:

  • Sammlungen im Plural: /api/appointments, /api/contacts. GET liest die Liste, POST legt ein neues Stück an.
  • Einzelstücke mit Kennung: /api/appointments/7. GET liest, PUT ersetzt, DELETE löscht.

Unterressourcen zeigen Zugehörigkeit: /api/contacts/12/appointments sind die Termine eines Kontakts. Mit Maß: Eine Ebene ist übersichtlich, drei Ebenen (/api/contacts/12/appointments/7/notes/3) zwingen den Aufrufer, Kennungen mitzuschleppen, die er gar nicht braucht. Hat ein Termin eine eigene Kennung, ist /api/appointments/7 seine Adresse, egal zu welchem Kontakt er gehört.

Und was ist mit Vorgängen, die kein Ding sind, etwa „einen Termin buchen“? Sie werden zu einem Ding: Eine Buchung ist eine Ressource, POST /api/bookings legt sie an. Die Kladde hat das seit Lektion 2.4.10 so.