Mastering @RequestHeader in Spring Boot

Learn how to use @RequestHeader in Spring Boot to handle HTTP headers for authentication, metadata, and client information with practical real-world examples.

What is @RequestHeader

@RequestHeader is a Spring Boot annotation used to bind HTTP header values to method parameters in a controller. It is mainly used to handle metadata rather than core business data. For example, headers like Authorization, Content-Type, or User-Agent provide additional context about the request.

In real-world systems, it is commonly used for authentication (JWT tokens), request tracing (request IDs), and API versioning. It supports required, optional, and default values, making it flexible for different use cases. Proper use of headers improves API security, traceability, and communication between distributed systems.

@RequestHeader is used in Spring Boot to extract values from HTTP request headers and bind them to method parameters, commonly for metadata like authentication tokens or client information in REST APIs.

In Spring Boot, @RequestHeader is used to extract values from HTTP request headers and bind them to method parameters. Headers usually contain metadata such as authentication tokens, content types, or client details.

Let’s start with a simple example:

@GetMapping("/api/data")
public String getData(@RequestHeader("User-Agent") String userAgent) {
    return "Client: " + userAgent;
}

When a request is made, Spring extracts the User-Agent header value and passes it to the method.

Now consider a real-world scenario where you need to validate an authentication token:

@GetMapping("/api/secure")
public String secureApi(@RequestHeader("Authorization") String token) {
    return "Token: " + token;
}

In production systems, this token is usually validated before processing the request.

You can also make headers optional:

@GetMapping("/api/info")
public String getInfo(
    @RequestHeader(value = "X-Request-Id", required = false) String requestId) {
    return "Request ID: " + requestId;
}

Or provide default values:

@GetMapping("/api/version")
public String getVersion(
    @RequestHeader(value = "version", defaultValue = "v1") String version) {
    return "API Version: " + version;
}

For multiple headers:

@GetMapping("/api/headers")
public String getHeaders(@RequestHeader Map<String, String> headers) {
    return headers.toString();
}

In Spring Boot, while @RequestHeader is commonly used to extract individual header values, you can also use HttpHeaders to handle multiple headers in a more flexible and scalable way. Let’s look at a basic example:

@GetMapping("/headers/http-headers")
public String readHeaders(@RequestHeader HttpHeaders headers) {
    return "User-Agent: " + headers.get("User-Agent");
}

Here, the entire request header is mapped into a HttpHeaders object, allowing you to access any header dynamically. Now consider a real-world scenario where you want to track client information and location:

@GetMapping("/headers/http-headers")
public String readRequestHeadersWithHttpHeaders(
        @RequestHeader HttpHeaders requestHeaders) {

    return "Received: " 
        + requestHeaders.get("User-Agent") 
        + " " 
        + requestHeaders.get("User-Location");
}

Example request headers:

User-Agent: Chrome

User-Location: India

This approach is very useful in production systems like microservices, where multiple headers such as Authorization, X-Request-Id, User-Agent, and custom headers are passed in every request.

In real-world applications like microservices or CRM systems, @RequestHeader is widely used for passing JWT tokens, tracking request IDs, handling API versioning, and managing client-specific data.

Best practices include validating sensitive headers like Authorization, avoiding overuse of headers for business data, and keeping header usage consistent across APIs.

Using @RequestHeader properly ensures secure, scalable, and well-structured APIs in production environments.