Topic: api-design
-
Using HTTP status codes correctly: the client's first branching point
Clients, caches and agents decide on the status code alone whether to retry, reload or give up: 201/204 for success with and without a body, 401 versus 403 for missing authentication versus missing permission, 409/412/428 for conflicts and preconditions, 429 and 503 with Retry-After for "later". A 200 with an error object misleads all of them.
-
Machine-readable error types reduce harmful retries by agents
Hypothesis: when an API returns stable problem types with retry hints, automated clients perform fewer retries of non-retryable requests and fewer duplicate writes than with prose-only errors; a proposed comparison.
-
Backing off as a client: Retry-After, RateLimit headers and per-host budgets
How an agent should react to 429 and 503 responses and to advisory rate-limit headers: honour Retry-After exactly, otherwise back off exponentially with jitter, read the RateLimit and RateLimit-Policy fields where a server sends them to pace ahead of the limit, keep a budget per host and per key, and never retry a non-idempotent write without an idempotency key.
-
Designing rate limits that protect the service and inform the client
Limit by the identity you can verify (account, network prefix), use atomic counters in fixed or sliding windows, answer 429 with Retry-After, keep separate budgets for reads, writes and registrations, and publish the effective limits.
-
Stripe API pagination and idempotency keys: starting_after, has_more and the 24-hour window
Stripe's v1 list endpoints paginate with the mutually exclusive starting_after/ending_before cursor parameters (limit 1-100, default 10) and a has_more flag, with client-library auto-pagination helpers to walk every page; POST requests can carry an Idempotency-Key whose saved result Stripe replays for about 24 hours, after which keys may be pruned. Rate-limited requests get 429 with a Stripe-Rate-Limited-Reason header.
-
Consistent naming and casing of JSON fields
Pick one case convention for property names and apply it everywhere: Google's JSON style guide and ProtoJSON use lowerCamelCase, many APIs use snake_case. Beyond case, keep names meaningful, enums as strings, timestamps as RFC 3339 strings and 64-bit integers as strings.
-
The Standard Webhooks spec versus Shopify's HMAC header and GitLab's shared-secret token
The Standard Webhooks specification defines webhook-id, webhook-timestamp and webhook-signature headers, a whsec_-prefixed base64 secret whose decoded bytes are the HMAC key, and a v1,<base64> signature over "{id}.{timestamp}.{payload}"; GitLab's signing tokens (GitLab 19.0, generally available in 19.1) implement exactly this. Shopify instead sends a base64 HMAC of the raw body in X-Shopify-Hmac-SHA256, and GitLab's older X-Gitlab-Token is a plain shared secret, not an HMAC at all.
-
Validating JSON with JSON Schema
JSON Schema describes the allowed shape of a document (types, required keys, enumerations, formats, bounds) and lets any language validate inputs before processing them; keep additionalProperties explicit.
-
Designing idempotent operations and safe retries
An operation is idempotent if executing it several times has the same effect as executing it once; RFC 9110 defines this for HTTP methods, and an Idempotency-Key header extends the property to POST. Store each key with a request fingerprint and the result, report conflicts with 409 and 422, and delete keys after a documented retention period.
-
Calling the TypeSafe API from an agent: request shape, errors, retries and version pinning
The documented contract an agent needs to call Jev without a chat layer: POST /v1/systemone with a Bearer key, a state, a model name and a map of typed questions; answers keyed like the questions plus a usage block; 401, 422, 429 and 529 with exponential backoff; aliases that move and versioned IDs that do not; SDK defaults for retries and the agent skill for coding agents.
-
Dry-run modes for agent actions: showing the plan before the change
Give every tool that changes state a mode that computes and returns the concrete plan (which objects, which fields, how many) without applying it, validate the plan on the server side where the system allows it, require the plan to be produced and reviewed before the real call, and compare the real result against it afterwards.
-
The Link header and link relation types
RFC 8288 lets any HTTP response carry typed links in a Link header: <target>; rel="relation" plus optional anchor, hreflang, type, title and media parameters. Relation names come from the IANA registry (next, prev, canonical, alternate, describedby, preload) or are absolute URIs for private extensions. It is how non-HTML responses point to their neighbours and how 103 Early Hints tells a browser what to fetch early.
-
HEAD and OPTIONS: what they answer and what clients use them for
HEAD is GET without the body: same status and headers (Content-Length and Vary may be omitted), cacheable, used for link checking, size probes and freshness checks. OPTIONS asks which communication options a resource or the whole server (OPTIONS *) supports, is typically answered with Allow, is not cacheable, and carries CORS preflights with Access-Control-Request-Method.
-
Verifying Slack request signatures: X-Slack-Signature, the 5-minute replay window and the 3-second rule
Slack signs requests as v0=<hex HMAC-SHA256> of the string "v0:{timestamp}:{raw body}" in the X-Slack-Signature header, paired with X-Slack-Request-Timestamp, which Slack's own example rejects once it differs from local time by more than five minutes. Slash commands and interactive payloads must additionally be acknowledged within three seconds, before any slow processing.
-
Designing an SDK on top of an HTTP API
An SDK should make the correct call the easy call: typed models, one client object holding configuration, uniform errors, retries with idempotency keys, pagination iterators and long-running-operation helpers, generated from the API description where possible and hand-written only where generation cannot express the intent.
-
Designing outgoing webhooks that receivers can trust
Sign each delivery with an HMAC over the body and a timestamp, deliver at least once with retries and idempotent event ids, keep payloads small with a link to fetch details, and let receivers verify without secrets in URLs.
-
Bulk endpoints and partial failure reporting
A bulk endpoint either succeeds or fails as a whole or reports per-item outcomes; a single 200 cannot express partial success, so choose one behaviour per endpoint, index failures by position, cap batch size, and apply authorisation and rate limits per item.
-
Choosing HTTP status codes deliberately
Status codes are the first thing a client branches on: 200/201/204 for success, 304 for unchanged, 400/422 for bad input, 401/403 for credentials versus permission, 404 for absent, 409/412/428 for conflicts and preconditions, 429/503 for later.
-
Agent-to-agent protocols in outline: A2A agent cards, tasks and where MCP fits
What the A2A protocol (version 1.0.0, Linux Foundation) standardises between independent agents: a published Agent Card at /.well-known/agent-card.json with capabilities, skills, endpoint and security schemes; tasks with a lifecycle of submitted, working, input-required, auth-required, completed, failed, canceled and rejected; messages and artifacts made of parts; JSON-RPC, gRPC and REST bindings; and the specification's own account of how it complements MCP.
-
Accept-Language negotiation and its limits
Accept-Language carries a weighted list of language ranges (da, en-gb;q=0.8, en;q=0.7); the server matches it against the languages it has using RFC 4647 filtering or lookup, answers with Content-Language and Vary: Accept-Language, and must fall back sensibly when the header is absent (Googlebot sends none) or wrong (a device locale is not a reader's choice). Use it for the first guess, not as the only selector.
Machine-readable: JSON