REST API Headers: Types, Examples, and Best Practices
Rohit Rajpal
Explore REST API headers with types, examples, and best practices to improve API communication, testing accuracy, and reliability.
REST API headers define rules and instructions for how requests and responses are handled. They carry metadata such as content type, authentication details, caching policies, and status information, making them essential for reliable client–server communication.
Request headers are used to pass details like tokens, accepted formats, or custom parameters, while response headers instruct clients on caching, redirection, rate limits, and error handling. Because headers directly affect security, performance, and usability, they play a central role in API testing and development.
This article explains what REST API headers are, why they matter, and the types of headers with practical examples.
Understanding REST API Headers
REST API headers are additional pieces of information sent along with an HTTP request or response. They are structured as simple key–value pairs and sit outside the main body of the message. While the body carries the actual data being transferred, headers define how that data should be processed.
For testers and developers, headers act as control signals that determine how clients and servers interact. Without the right headers, even valid requests may fail, or responses may be misinterpreted. For example, a missing Content-Type header can prevent the server from understanding whether the payload is JSON, XML, or another format.
Why Use REST API Headers?
REST API headers carry the information that defines how communication between client and server should work. They separate metadata from the main request or response body, making interactions more reliable, secure, and efficient.
Here are the main reasons headers are used in REST APIs:
- Content negotiation: Headers such as Content-Type and Accept define how data is formatted and understood. A client may request JSON while another requests XML from the same endpoint.
- Authentication and authorization: The Authorization header passes tokens, API keys, or credentials that control access to resources.
- Caching control: Headers, such as Cache-Control, Expires, and ETag, specify how responses are stored and reused, improving performance and reducing server load.
- Session management: Response headers such as Set-Cookie maintain user sessions across multiple requests.
- Error handling and rate limiting: Headers, such as Retry-After or X-RateLimit-Limit, guide clients on when to retry requests and how many requests are allowed within a given window.
- Cross-origin requests: Security headers such as Access-Control-Allow-Origin define whether resources can be shared across domains.
REST API Request Headers Examples
Request headers are sent by the client to provide the server with details about the request. They shape how the server interprets the request and often determine whether the server accepts or rejects it.
Unlike the request body, which carries the main data payload, request headers carry metadata such as authentication, preferred response format, or custom instructions.
Here are common request headers with examples and their role in practice:
1. Authorization
Used to send credentials such as API keys, bearer tokens, or basic authentication strings. For example:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...
This header ensures that only authenticated clients can access protected endpoints.
2. Content-Type
Informs the server about the media type of the request body. For example:
Content-Type: application/json
This tells the server that the body of the request is JSON and should be parsed accordingly.
3. Accept
Tells the server which response formats the client can handle. For example:
Accept: application/json
A client that requests JSON will receive a JSON response if the server supports it.
4. User-Agent
Provides information about the client making the request, such as browser or application details. For example:
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
This can be useful for analytics, debugging, or tailoring responses.
5. Cache-Control
Controls how requests interact with caching mechanisms. For example:
Cache-Control: no-cache
This tells the server not to use cached content and to fetch fresh data.
6. Custom headers
Developers often add custom headers to pass application-specific data. For example:
X-Client-Version: 1.2.0
Custom headers should be prefixed with X- or another convention agreed upon within the system.
REST API Response Headers Examples
Response headers are sent by the server to provide clients with information about the response and instructions on how it should be handled. While the body carries the actual data, response headers define behavior around caching, security, redirection, and session handling. For testers and developers, these headers are critical to validating whether the server is behaving as intended.
Here are the most important response headers with examples and their practical role:
1. Content-Type
Defines the format of the response body. For example:
Content-Type: application/json; charset=utf-8
This tells the client that the response is in JSON and uses UTF-8 encoding. If the client is expecting XML but receives JSON, this header helps detect the mismatch quickly.
2. Cache-Control
Instructs clients and proxies how to cache the response. For example:
Cache-Control: max-age=3600
This means the response can be cached for 3600 seconds. Testers often verify this to ensure performance optimization does not compromise the freshness of data.
3. Set-Cookie
Used to establish or update cookies on the client. For example:
Set-Cookie: sessionId=abc123; HttpOnly; Secure; Path=/
This header manages user sessions. Security flags such as HttpOnly and Secure are important to validate during testing.
4. Location
Sent during redirection to specify the new URL. For example:
Location: https://api.example.com/v2/resource
When testing, this helps confirm that resources have moved correctly or that API versioning is handled as expected.
5. Retry-After
Informs the client when to retry a request, often after rate limiting or server overload. For example:
Retry-After: 120
This tells the client to wait 120 seconds before retrying. Testers rely on this to confirm proper throttling behavior.
6. Access-Control-Allow-Origin
Part of CORS (Cross-Origin Resource Sharing). For example:
Access-Control-Allow-Origin: *
This header controls whether the response can be shared with requests from different origins. Security testing often involves ensuring that this is not overly permissive in production systems.
7. Content-Disposition
Defines how content should be displayed in the browser. For example:
Content-Disposition: attachment; filename="report.pdf"
This forces the response to be downloaded as a file. Testers check this to verify file delivery works correctly.
8. Server
Provides information about the software handling the request. For example:
Server: Apache/2.4.41 (Ubuntu)
While informative, exposing server details can be a security risk. Security testing often includes verifying whether this header should be masked.
How REST API Headers Work in Practice
Every HTTP request and response follows a structured format where headers are evaluated before the body is processed.
Here’s how headers operate step by step in practice:
1. Client sends a request with headers
The client includes headers to define the request context. For example:
POST /api/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...
Content-Type: application/json
Accept: application/json
- Authorization tells the server who the client is.
- Content-Type specifies that the body is JSON.
- Accept signals that the client expects JSON in return.
2. Server validates the request headers
The server checks whether the request includes the required headers. Missing or invalid headers often result in errors such as 401 Unauthorized or 415 Unsupported Media Type.
3. Server processes the request body using the header context
Since the Content-Type header is application/json, the server parses the request body accordingly. If this header were incorrect, the server might fail to interpret the data.
4. Server sends a response with headers
After processing, the server sends headers that define how the client should handle the response:
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
Location: https://api.example.com/orders/12345
- Content-Type ensures the client knows the response format.
- Cache-Control prevents caching of sensitive data.
- Location points to the newly created resource.
5. Client interprets the response using headers
The client uses these headers to decide the next steps. In this case, it can parse the JSON, avoid storing it in cache, and use the Location header to fetch the newly created order.
In real-world API testing, headers are often the first signals testers check when debugging issues. A missing Authorization header might block access, a mismatched Content-Type can break data exchange, and an incorrect Cache-Control can cause stale responses. Verifying these interactions ensures both client and server handle requests predictably.
Why Use Requestly for REST API Headers?
Working with REST API headers often requires modification and debugging during development and testing. Testers may need to inject custom headers, remove unnecessary ones, or rewrite them to simulate different client behaviors. Doing this manually or by modifying source code can be slow and error-prone. This is where a tool like Requestly becomes valuable.
Requestly allows developers and testers to intercept, inspect, and modify API headers directly in real time. Instead of changing server code or rebuilding a client, headers can be adjusted instantly at the network level. This makes it easier to validate how an API responds under different conditions.
Here are the key ways Requestly helps with REST API headers:
- Modify headers instantly: Add, update, or remove request and response headers without changing application code. This is useful for testing scenarios like expired tokens or unsupported content types.
- Debug authentication flows: Simulate different Authorization header values, such as expired JWTs or invalid API keys, to confirm how the server handles failures.
- Test caching behavior: Adjust headers like Cache-Control and ETag to verify how responses are cached and revalidated.
- Validate cross-origin requests: Experiment with headers like Access-Control-Allow-Origin to check how CORS policies affect browser-based clients.
- Automate rules for repeat testing: Save header modification rules so they apply automatically in future sessions, reducing repetitive manual setup.
Best Practices for Working with REST API Headers
Headers are powerful because they control how requests and responses behave, but misusing or neglecting them can create security gaps, performance issues, or broken integrations. Following best practices ensures headers are consistent, predictable, and reliable across different environments.
Here are the recommended practices for working with REST API headers:
- Use standard headers consistently: Always prefer standard headers such as Content-Type, Authorization, Accept, and Cache-Control over custom ones where possible. Standardization reduces confusion and makes APIs easier to consume.
- Keep custom headers clear and documented: If custom headers are required, prefix them (for example, X-Client-Version) and document their purpose. This avoids ambiguity for testers and other teams integrating with the API.
- Validate headers during testing: Always check that required headers are present and correct. For example, verify that Authorization is enforced for sensitive endpoints, or that Content-Type matches the request body.
- Secure sensitive information: Ensure headers carrying credentials or tokens, such as Authorization, are sent over HTTPS. Avoid exposing secrets in headers that may be logged or cached.
- Use caching headers deliberately: Test and configure headers like Cache-Control, Expires, and ETag to balance performance with freshness of data. Misconfigured caching often leads to stale or inconsistent responses.
- Leverage CORS headers carefully: Limit Access-Control-Allow-Origin to trusted domains rather than using a wildcard (*) in production environments. This prevents unauthorized cross-origin access.
- Handle error and rate-limit headers correctly: Verify that headers such as Retry-After and X-RateLimit-Limit are set and that clients respond to them properly. This ensures graceful handling of throttling scenarios.
Conclusion
REST API headers define how clients and servers exchange information beyond the data in the request or response body. They control aspects such as content type, authentication, caching, session management, and cross-origin access.
Requestly helps developers and testers manage REST API headers without changing code. It allows you to intercept and modify headers in real time, making it easier to test scenarios such as expired tokens, incorrect content types, caching rules, or CORS restrictions.
Written by
Rohit Rajpal
Rohit Rajpal is a B2B Content Strategist at BrowserStack, helping SaaS brands build AI-first strategies that drive authority and revenue. He writes about content, strategy, and the future of search in the zero-click era.
Contents
Subscribe for latest updates
Share this article
Related posts
FastAPI POST Tutorial: Creating and Validating APIs
Learn to create and validate POST APIs in FastAPI with Pydantic models, handle various data types, test effectively, and debug with Requestly interceptor.
Rashmi Saini
September 17, 2025
Understanding Dummy API for React Apps
Learn how dummy APIs accelerate React development by providing static data for seamless UI building and testing without backend dependency.
Rashmi Saini
September 17, 2025
Following-Sibling XPath in Selenium: Complete Guide
Learn how to use following-sibling XPath in Selenium for precise element selection, handling dynamic content, and creating reliable automation scripts.
Rohit Rajpal
September 17, 2025