FresherTechnicalAPI design
Which HTTP headers matter most in an API request and response?
Try answering first
Model answer
Headers carry metadata about the message, so the body can stay focused on data. These are the ones an API designer uses daily.
Request headers
Content-Type: the format of the body you send, such asapplication/json.Accept: the formats the client can read.Authorization: credentials, for exampleBearer <token>.Idempotency-Key: lets a client retry aPOSTsafely.If-None-MatchandIf-Match: conditional reads and writes with anETag.
Response headers
Content-Type: the format of the response.Location: the URL of a new resource after201, or of a job after202.Cache-ControlandETag: caching and validation.Retry-AfterandRateLimit-*: throttling guidance.WWW-Authenticate: sent with401to say how to authenticate.Link: pagination links.
For debugging, return a request id such as X-Request-Id, or use the W3C traceparent header so support can find a call in the logs.
Headers are for metadata. Data the client is working on belongs in the body.
Key points
- Content-Type and Accept negotiate formats
- Authorization carries credentials
- Location, ETag and Cache-Control describe resources and caching
- A request id header helps debugging
Likely follow-ups
- What does the WWW-Authenticate header do?
- How do you propagate a trace id between services?
Common mistakes
- Putting business data in custom headers
- Forgetting Content-Type on responses