HTTP semantics that matter

HTTP already defines a lot of behaviour. An API that uses it as intended gets caching, retries and tooling support for free. The current specification is RFC 9110, HTTP Semantics.

Methods and their promises

Each method makes a promise about what it does, and clients, proxies and caches rely on those promises:

• GET: read a resource. Safe (no side effects) and idempotent.
• HEAD: like GET without the body. Safe and idempotent.
• POST: create a resource or trigger a process. Neither safe nor idempotent by default.
• PUT: replace a resource completely at a known URL. Idempotent.
• PATCH: change part of a resource. Not guaranteed to be idempotent.
• DELETE: remove a resource. Idempotent.

Safe means the client does not request a change. Crawlers, caches and prefetching rely on this, so a GET that deletes something is a serious bug waiting to happen.

Idempotent means making the same request once or ten times has the same effect on the server. Deleting booking 42 twice leaves it deleted. The second call might return 404 instead of 204, which is fine: the state is the same. Clients and proxies may automatically retry idempotent requests after a network failure.

Why this matters for Slotly

Creating a booking is a POST, so it is not idempotent. If the client times out and retries, we might create two bookings. We fix that later with idempotency keys. Cancelling a booking could be DELETE /bookings/42 or, if we want to keep a record, POST /bookings/42/cancel. We discuss that choice in the resource modelling section.

Headers worth knowing

• Content-Type and Accept: the format of the body and the format the client wants.
• Authorization: credentials, usually a bearer token.
• ETag and If-None-Match: conditional requests for caching.
• If-Match: optimistic concurrency, preventing lost updates.
• Location: the URL of a newly created resource, returned with 201.
• Retry-After: how long to wait, used with 429 and 503.
• Cache-Control: whether and how long a response may be cached.

Status code classes

• 2xx: success
• 3xx: redirection
• 4xx: the client should change something before retrying
• 5xx: the server failed; retrying later might work

That last distinction is the most important one for clients. A 4xx tells the client the request itself was wrong. A 5xx tells it the server had a problem. Getting this right lets clients decide automatically whether to retry.