#http

Articles tagged with #http

Your JSON Is Valid. Your Content-Type Might Not Be.
A practical way to separate request format errors from response negotiation problems, with cURL examples and a four-case regression checklist.
Oct 9, 20263 min read
File downloads in OpenAPI: CSV, PDF, ZIP, images, Content-Disposition, and non-JSON responses
APIs return more than JSON: CSV exports, PDF invoices, ZIP archives, resized images, and generated audio. Model them with the right media type and string/binary schema, document Content-Disposition and Range, and distinguish inline from attachment. Here is how to describe downloa
Oct 8, 20266 min read
Deprecating an API without breaking clients: Deprecation and Sunset headers, successor-version, and OpenAPI
Deleting an endpoint is not a deprecation policy, and announcing it once in a changelog does not reach the integrations that actually call it. RFC 8594 gives you the Deprecation and Sunset response headers, Link rel=successor-version points at the replacement, and OpenAPI ma
Oct 8, 20266 min read
Idempotency-Key in practice: retrying POSTs safely, deduping concurrent requests, and documenting it in OpenAPI
A network timeout never tells the client whether the charge happened. Retrying a plain POST double-creates; an Idempotency-Key header turns the retry into a replay. Here is the header contract, the in-flight 409 versus the stored response, key lifetime and scope, and the OpenAPI
Oct 8, 20266 min read
Bulk and batch API endpoints: modeling create-many, partial success, and 207 Multi-Status in OpenAPI
Looping 500 POSTs from the client is slow and fails halfway with no way to recover. A bulk endpoint accepts an ordered batch and reports each item independently, including partial success with 207 Multi-Status. Here is the request envelope, per-item status and error arrays, idemp
Oct 8, 20266 min read
Long-running REST APIs: 202 Accepted, Location, job status polling, and webhooks in OpenAPI
Holding an HTTP connection open for a three-minute export times out and ties up workers. Return 202 Accepted with a Location to a job resource, model the job state machine, and let clients poll or subscribe to a webhook. Here is the full lifecycle with progress and cancellation,
Oct 8, 20267 min read