Choosing the Right Content-Type for REST APIs

Content-Type Headers for REST APIs

The Content-Type header is critical for APIs because it tells the server how to parse the request body and tells the client how to parse the response.

Common API Content Types

Content-Type	When to use
application/json	JSON request/response bodies (most common)
application/x-www-form-urlencoded	Simple HTML form submissions
multipart/form-data	File uploads with metadata
application/xml	SOAP or legacy XML APIs
text/plain	Raw text payloads
application/octet-stream	Raw binary uploads

JSON API Request

POST /api/users HTTP/1.1
Content-Type: application/json

{"name": "Alice", "email": "alice@example.com"}

Form URL-Encoded Request

POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded

username=alice&password=secret

Content Negotiation with Accept

The Accept header lets clients request a specific response format:

GET /api/users/1 HTTP/1.1
Accept: application/json

Versioned API Media Types

Some APIs use vendor-specific types for versioning:

Accept: application/vnd.myapi.v2+json

Error Responses

RFC 7807 defines application/problem+json for standardized error objects:

{
  "type": "https://example.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "User 42 does not exist."
}