Org Skills
Referenceapi-design

HTTP semantics reference

Supporting material for api-design. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified 2026-09 against https://www.rfc-editor.org/rfc/rfc9110.html (HTTP semantics), https://www.rfc-editor.org/rfc/rfc9457.html (problem+json), https://www.rfc-editor.org/rfc/rfc9745.html (Deprecation), https://www.rfc-editor.org/rfc/rfc8594.html (Sunset) and https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/.

1. Status codes, and the ones people get wrong

Code Use for Commonly misused as
200 A successful read or update with a body A failure with "success": false in the body
201 Created — with a Location header Returned without Location, so the client cannot find the resource
202 Accepted for later processing — with a way to track it A synchronous success the caller then polls for nothing
204 Success, deliberately no body Returned with a body, which some clients discard
304 Not Modified, in response to If-None-Match/If-Modified-Since Rarely used at all, so bandwidth is wasted
400 The request is malformed — unparseable, wrong types Used for every error including business rules
401 No or invalid credentials Used when the caller is authenticated but lacks permission
403 Authenticated, not allowed Used where 404 belongs, confirming the resource exists
404 Not found — and for resources the caller may not see Used for a malformed id, which is 400
409 State conflict: the resource is not in a state allowing this Used for validation failures
412 If-Match did not match — someone else changed it Silently overwriting instead
415 Unsupported media type 400
422 Syntactically valid, semantically wrong 400, losing the distinction clients need
428 Precondition required — you must send If-Match Accepting the unconditional write
429 Rate limited — with Retry-After Sent with no hint of when to return
500 An unexpected failure — a bug Used for downstream failures, which are 502/503/504
503 Temporarily unavailable — with Retry-After 500, so clients do not know it is retryable

The 400 / 422 split earns its keep: 400 means "I could not read this", 422 means "I read it and it is wrong". A client can retry neither, but a developer debugging one looks in a very different place.

2. Conditional requests end to end

Caching a read:

GET /orders/42 HTTP/1.1

HTTP/1.1 200 OK
Cache-Control: private, max-age=60
ETag: "v7-a1b2c3"
GET /orders/42 HTTP/1.1
If-None-Match: "v7-a1b2c3"

HTTP/1.1 304 Not Modified
ETag: "v7-a1b2c3"

Guarding a write with the same tag:

PATCH /orders/42 HTTP/1.1
If-Match: "v7-a1b2c3"
Content-Type: application/merge-patch+json

{ "shippingAddress": { "postcode": "SW1A 1AA" } }

412 Precondition Failed if the tag no longer matches; 428 Precondition Required if the header is missing and your policy requires it. The client's correct response to 412 is to re-read, re-apply its change and retry — say so in the documentation, because the naive response is to retry without the header and clobber the other writer.

Generate the ETag from something that changes with the row: a version column or a hash of the representation. A timestamp with one-second resolution allows two writes in the same second to collide silently.

Cache-Control choices: private for anything tied to the caller, no-store for anything sensitive, public only where the response genuinely does not depend on who asked. Getting this wrong puts one user's data in a shared proxy.

3. Headers and their sources

Header Defined by Notes
ETag, If-Match, If-None-Match, Cache-Control, Retry-After, Location RFC 9110 Core HTTP; every client and proxy understands them
Content-Type: application/problem+json RFC 9457 The error format for this catalog
Deprecation RFC 9745 Structured-field Date: Deprecation: @1735689600
Sunset RFC 8594 HTTP-date: Sunset: Wed, 31 Dec 2026 23:59:59 GMT. Must not be earlier than Deprecation
Link: …; rel="deprecation" RFC 9745 Points at the migration guide
RateLimit, RateLimit-Policy IETF draft (draft-11, May 2026) Not an RFC. Widely implemented, still changing
RateLimit-Limit, -Remaining, -Reset De facto Older convention, still the most widely consumed
Idempotency-Key De facto (Stripe-style) The IETF draft expired in October 2025 without becoming an RFC
traceparent, tracestate W3C Trace Context Accept and propagate them (service-operability)

The point of this table is to stop two failure modes: citing an RFC number that does not exist for a header, and implementing a draft as though it were settled. For Idempotency-Key and the rate-limit fields, document your own semantics — that is what clients will code against.

4. Deprecating a field or an endpoint

HTTP/1.1 200 OK
Deprecation: @1735689600
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/docs/v2-migration>; rel="deprecation"; type="text/html"

The sequence that actually works:

  1. Add the replacement alongside the old field. Both are populated.
  2. Mark the old one deprecated: true in the OpenAPI document and start sending the headers.
  3. Measure usage per client. This is the step that gets skipped, and it is the only one that tells you whether removal is safe.
  4. Contact the remaining consumers directly. A header is not a conversation.
  5. Remove after the sunset date, in a major version.

A field-level deprecation inside a version is legitimate — deprecated: true on a schema property is part of OpenAPI — and is much cheaper than a whole new major version for one rename.

5. Batch and bulk

POST /orders:batch HTTP/1.1
Content-Type: application/json

{ "items": [ { "sku": "A1", "qty": 2 }, { "sku": "B2", "qty": 0 } ] }
HTTP/1.1 200 OK
Content-Type: application/json

{ "results": [
    { "index": 0, "status": 201, "id": "01JD…" },
    { "index": 1, "status": 422,
      "error": { "type": "https://api.example.com/problems/validation",
                 "title": "qty must be >= 1", "status": 422 } } ] }

Rules that make a batch endpoint usable:

  • Per-item status. One bad row must not fail the batch, and the caller must be able to tell which.
  • The envelope status is about the envelope: 200 means "I processed your batch", not "everything succeeded". Document this loudly — it surprises people.
  • Cap the item count and return 413 or 422 above it. An uncapped batch is an unplanned long-running request.
  • Partial success is the default; offer all-or-nothing only if you can really do it in one transaction, and say which you are.
  • Idempotency applies to the batch as a whole: one Idempotency-Key for the request, so a retry does not half-repeat it.

6. Webhook delivery

Sending:

POST /hooks/orders HTTP/1.1
Webhook-Id: 01JD8ZQ3H7
Webhook-Timestamp: 1767225600
Webhook-Signature: v1,5d41402abc4b2a76b9719d911017c592
Content-Type: application/json

{ "id": "01JD8ZQ3H7", "type": "order.placed", "occurredAt": "2026-01-01T00:00:00Z",
  "resource": "https://api.example.com/orders/42" }
  • Sign over the timestamp and the raw body with HMAC-SHA256 and a per-subscriber secret. Receivers verify in constant time and reject a timestamp older than a few minutes, which is what stops a captured request being replayed forever.
  • Support two secrets at once so a subscriber can rotate without dropping deliveries.
  • Delivery is at least once. The id is what lets the receiver deduplicate — the receiving side of this is messaging-patterns §3.
  • Retry with capped jittered backoff over hours, then dead-letter and expose a replay endpoint. Disable a subscription that has failed for days, and tell its owner.
  • Thin events — id, type, and a URL to fetch the resource — avoid leaking data to a stale endpoint and avoid versioning a full payload. The cost is a callback, which is usually worth it.