Representational state transfer (REST) is an architectural style for designing APIs that relies on stateless client-server communication and a uniform interface. REST APIs use HTTP requests to perform create, read, update, and delete operations.
HTTP headers allow the client and server to send additional information with the request and response. Headers consist of a field name and value separated by a colon. For example: Content-Type: application/json
Headers are an important part of REST APIs. They allow the API to be stateless by providing all the context for processing the request in each individual message. Headers can be used for many purposes like authentication, providing information about the content, pagination, caching, rate limiting and more.
Common uses of headers in REST APIs
Here are some of the most common uses of headers in REST APIs:
Content Type
The Content-Type header indicates the media type of the resource being sent in the request body or response body. It allows the API and clients to interpret the content correctly.
For example, to specify that the request body contains JSON:
Content-Type: application/json
Common content types for REST APIs include:
- application/json for JSON data
- application/xml for XML data
- text/plain for plain text
- multipart/form-data for file uploads
Accept
The Accept header is used to specify the media types the client can understand. For example:
Accept: application/json
This tells the API to return JSON formatted data if possible. The API will send an error if it cannot provide the response in one of the acceptable formats.
Authorization
The Authorization header is used to send credentials for authentication and authorization. The most common authorization scheme used in REST APIs is OAuth 2.0 where an access token is passed:
Authorization: Bearer 401f7ac837da42b97f613d789819ff93537bee6a
Basic authentication is another scheme where username and password are encoded:
Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
User Agent
The User-Agent header identifies the client making the request. It can include information like software version and operating system.
User-Agent: MyApp/1.0 (Linux; Android 8.1)
This helps the API identify the client and can be useful for analytics, debugging issues, and providing customized responses.
Using Headers for Versioning
Headers provide a nice way to handle versioning in a REST API. When making breaking changes, a new API version can be indicated via a custom header like:
Api-Version: 2
The API can then route requests to the appropriate backend code based on the provided version. Other versioning approaches like putting the version in the URL can also work but require more changes when upgrading versions.
Pagination Headers
APIs commonly use headers to handle pagination for list endpoints that return multiple resources. For example, the Link header can provide references to the next and previous pages:
Link: </api/users?page=2>; rel="next", </api/users?page=5>; rel="last"
And headers like Total-Count and Page-Size can provide more context:
Total-Count: 423 Page-Size: 25
This keeps the pagination logic centralized in the API and out of the client code.
Security Headers
There are a number of HTTP headers that are useful for improving the security of an API including:
- Strict-Transport-Security to enforce HTTPS
- Content-Security-Policy for mitigating cross-site scripting (XSS)
- X-Frame-Options to prevent clickjacking
These headers require some configuration on the server but allow APIs to be locked down and follow security best practices with little effort.
Custom Headers
APIs can also leverage custom headers for specific use cases like:
- Rate limiting – X-Rate-Limit-Limit, X-Rate-Limit-Remaining
- Error tracking – X-Request-Id
- Client data – X-Client-Language
Custom headers should be prefixed with X- to avoid collisions with future standard headers.
Best Practices for Using Headers
Here are some best practices to follow when using headers in a REST API:
- Use common headers correctly – Content-Type, Accept, Authorization, etc.
- Version APIs using custom headers like Api-Version
- Pagination should rely on Link and other pagination headers
- Include security headers like CORS and XSS protection
- Document custom headers so clients know how to use them
- Don’t overload headers – use request parameters for extensive data
- Avoid vendor-specific headers when possible
Tools for Working with Headers
There are a variety of tools that can assist with debugging, viewing, and modifying headers:
- cURL – Command line tool that allows setting custom headers
- Postman – GUI with comprehensive header support
- HTTPie – User friendly command line HTTP client
- Browser DevTools – Built in tools for viewing request/response headers
- Charles Proxy – HTTP debugging proxy with header management features
Trying out requests with different headers is easy with these tools. They are invaluable when working with REST APIs.
Conclusion
HTTP headers are a foundational component of REST APIs. They enable versioning, pagination, security, rate limiting, and other key capabilities. Standard headers should be used properly and custom headers can enable specialized functionality.
Careful use of headers allows REST APIs to follow best practices and deliver robust functionality to clients. They provide a stateless way to send metadata along with requests and responses.
There are many developer tools available for modifying headers during testing which assists with API development. Overall headers are a critical mechanism for building production-ready RESTful interfaces.