HTTP as a Distributed Systems API (Without the Buzzwords)

• Safe method: an HTTP method that is intended to be read-only (no state change), e.g. GET.
• Idempotent method: repeating the same request produces the same state result (even if the response differs), e.g. PUT, DELETE (in intended semantics).
• Cacheable response: a response intermediaries are allowed to store and reuse under rules.
• Conditional request: a request that says “only send me the body if it changed” (e.g., using ETag).
• Deadline: a time budget for the whole operation, not just one hop.
• At-least-once delivery: the reality that a request may be processed more than once due to retries/timeouts.

Use for resource retrieval and queries.

Design expectations

• safe (no state change)
• should be idempotent
• may be cached (with correct headers)

Common mistakes

• using GET to trigger side effects (“track view”, “send email”)
• leaking sensitive data into URLs

Use when the server assigns identity or the action is non-idempotent by default.

Design expectations

• not idempotent unless you design it to be
• must be safe to retry with an idempotency key for important actions

Good patterns

• POST /orders to create a new order
• POST /orders/{id}/submit as a command (explicitly a state transition)

Use when the client knows the resource identity and sends the full desired state.

Design expectations

• idempotent (repeat should converge)
• good for “set this exactly” behavior

Common mistakes

• partial updates via PUT without documenting merge semantics

Use for partial updates when replacement is wasteful.

Design expectations

• may or may not be idempotent depending on patch semantics
• document whether patches are merge-based or operation-based

Common mistakes

• undocumented patch formats
• non-repeatable patches that break retries

Design expectations

• calling DELETE twice should not break anything
• response codes may differ (200/204 vs 404), but the state should converge

Common mistakes

• “soft delete” semantics that aren’t documented
• deletes that trigger cascading side effects without idempotency planning

• Decide: public vs private vs no-store for every response type.
• Define cache keys intentionally (URL + relevant headers via Vary).
• Avoid caching personalized responses at shared layers unless you can prove it’s safe.
• Prefer validators (ETag / Last-Modified) for frequently accessed resources.
• Be explicit about TTLs; “defaults” vary across intermediaries.
• Test your cache behavior in staging with real headers and real proxies/CDNs.

Semantics

• Methods chosen for safety/idempotency, not “style”.
• Idempotency keys for actions that must not duplicate.
• Conflict handling (409) for concurrent updates.

Caching

• Explicit cache policy for every response type.
• Public vs private vs no-store is intentional.
• Validators (ETag) used for high-traffic resources.
• Vary is explicit and safe.

Errors

• Error bodies are structured and stable.
• 4xx codes guide corrective client behavior.
• 5xx codes indicate retriable vs non-retriable failure policy.

Resilience

• Deadlines enforced.
• Retries have budgets + backoff + jitter.
• Rate limiting is contractual (429 + headers if you use them).

Security

• Auth/private responses are not accidentally cached publicly.
• Sensitive data is not placed in URLs.
• TLS everywhere; security headers in place.

Typical root cause

• POST actions not protected by idempotency keys
• client retries after timeout

Fix

• idempotency keys + server-side dedupe
• move long work behind 202 + async processing

Typical root cause

• caching personalized content in shared caches
• missing or incorrect Vary behavior

Fix

• private / no-store where needed
• strict cache keys and explicit Vary
• separate public and authenticated origins/routes

Typical root cause

• intermediaries rewriting headers
• CORS / cookies behaving differently
• missing timeouts / different defaults

Fix

• test through realistic proxies/CDN in staging
• explicit headers, explicit timeouts, explicit policies

Typical root cause

• retry storms
• no budgets, no backoff, synchronized clients

Fix

• retry budgets, backoff+jitter
• circuit breakers and load shedding where appropriate

Not really.

This is about HTTP semantics—which REST uses, but which also apply to “RPC-ish” APIs.

You can build a pragmatic API style and still benefit from:

• idempotency rules
• caching rules
• status code signals
• deadlines and retry safety

No.

But you do need consistency and clarity—especially for:

• 401 vs 403
• 404 vs 409
• 429 and retry behavior
• 202 for async work

Status codes are less about purity and more about client behavior under failure.

Treat ambiguity as normal.

Assume:

• requests can be retried
• responses can be cached
• intermediaries exist
• timeouts don’t mean “didn’t happen”

Then design your operations so repeating them doesn’t break the world.