The Kladde has had an API since module 2.3. It delivers contacts and appointments, knows status codes, describes itself in an OpenAPI document, and delivers contacts in pages (lesson 2.3.10). With module 2.12, callers come along who are not you: another program, a partner, later a gateway. For them, more counts than "it works." A list must not swallow an appointment while paging, two people must not overwrite each other's changes, and a booking that arrives twice because of a network error must be booked only once. In this lesson you cut the appointment API so that exactly that holds.

Resources instead of verbs

A REST API describes things, not actions. The action is in the method:

Instead of Better Why
POST /api/createAppointment POST /api/appointments the method says "create"
GET /api/getAppointment?id=7 GET /api/appointments/7 a single item has an address of its own
POST /api/appointments/7/delete DELETE /api/appointments/7 DELETE is idempotent, a POST is not

Two forms carry almost every API:

  • Collections in the plural: /api/appointments, /api/contacts. GET reads the list, POST creates a new item.
  • Single items with an identifier: /api/appointments/7. GET reads, PUT replaces, DELETE deletes.

Sub-resources show belonging: /api/contacts/12/appointments are the appointments of a contact. In moderation: one level is easy to survey, three levels (/api/contacts/12/appointments/7/notes/3) force the caller to carry along identifiers that he doesn't need at all. If an appointment has an identifier of its own, /api/appointments/7 is its address, no matter which contact it belongs to.

And what about operations that aren't a thing, such as "book an appointment"? They become a thing: a booking is a resource, POST /api/bookings creates it. The Kladde has done it this way since lesson 2.4.10.