2026-09-12 · 8 min read
- http
- redirects
- api-design
Redirects separate an initial request from a follow-up request chosen by the client. The Location header identifies a target, while the status code and client policy determine the follow-up method, content, credentials, and cache behavior.
That distinction is easy to miss when a browser navigation looks correct but an API write loses its body, repeats a side effect, or crosses an origin with authentication attached.
Select status semantics from the operation
Use 303 when the intended follow-up is retrieval of another resource after a write. Use 307 or 308 only when the recipient is prepared to receive the original method and content. Legacy behavior around 301 and 302 varies enough that every supported non-GET client needs an explicit test.
- Treat 301 and 308 as cacheable permanent migration signals.
- Keep 302 and 307 temporary when the canonical mapping may change.
- Avoid redirecting machine writes when clients can use the final endpoint.
- Reject unsupported methods at both the old and new destinations.
Plan for replay and non-rewindable bodies
A preserved-method redirect asks the client to send content again. Buffered JSON may be replayable, while an upload stream, generated body, or one-shot request object may not be. State-changing operations should use application-level idempotency where duplicate delivery is possible.
Do not confuse redirect following with a retry policy. A redirect changes the request target; retries repeat an attempt after uncertainty. Both can occur in one chain and must share a bounded replay budget.
Constrain origins, credentials, and caches
Resolve and parse Location before comparing its scheme, host, and port with an allowlist. Do not automatically forward Authorization, cookies, client certificates, signed headers, or private query parameters to a different origin.
- Prefer HTTPS and reject unintended downgrade redirects.
- Strip user information from accepted redirect targets.
- Bound hop count and detect loops.
- Account for cached permanent redirects during rollback.
Test the complete client matrix
Use Flashman's URL tool for public redirect targets, JSON formatter for synthetic request bodies, diff for hop metadata, timestamp converter for traces, and hash tool for fixture identities. These tools inspect data but do not implement an HTTP redirect stack.
Exercise 301, 302, 303, 307, and 308 with GET, HEAD, POST, PUT, and DELETE; relative references; fragments; query strings; same-origin and cross-origin targets; HTTPS upgrades and downgrades; streamed bodies; authentication; cache warm and cold states; loops; retry interaction; proxies; browsers; CLIs; mobile clients; and generated SDKs.