Custom response headers in Spring Boot - Deep Dive

Overview - Custom response headers

What is it?

Custom response headers are extra pieces of information that a server adds to its reply when you ask for something on the web. These headers are like labels attached to the response, telling the browser or client more about the data or how to handle it. In Spring Boot, you can easily add these headers to control behavior or share extra details. They help customize communication between your server and clients beyond the standard data.

Why it matters

Without custom response headers, servers would only send basic information, limiting control over how clients process responses. Custom headers let you add security details, caching rules, or metadata that improve user experience and app performance. For example, telling browsers to cache data or share version info helps apps run faster and safer. Without them, developers would struggle to fine-tune interactions between servers and clients.

Where it fits

Before learning custom response headers, you should understand basic HTTP concepts like requests, responses, and standard headers. Knowing how Spring Boot handles web requests and responses is also important. After mastering custom headers, you can explore advanced topics like security headers, CORS configuration, and response filtering in Spring Boot.

Mental Model

Core Idea

Custom response headers are extra labels a server adds to its reply to guide how clients handle the response.

Think of it like...

It's like sending a package with a note attached that says 'Fragile' or 'Keep refrigerated' so the receiver knows how to treat it.

┌───────────────────────────────┐
│ HTTP Response                 │
│ ┌───────────────────────────┐ │
│ │ Status Line               │ │
│ ├───────────────────────────┤ │
│ │ Standard Headers          │ │
│ │ - Content-Type            │ │
│ │ - Content-Length          │ │
│ ├───────────────────────────┤ │
│ │ Custom Headers            │ │
│ │ - X-App-Version           │ │
│ │ - X-Cache-Duration        │ │
│ ├───────────────────────────┤ │
│ │ Body                     │ │
│ └───────────────────────────┘ │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding HTTP response headers

Concept: Learn what HTTP response headers are and their role in web communication.

When a client (like a browser) asks a server for data, the server replies with a response. This response has a status (like 200 OK) and headers. Headers are lines of text that give extra info about the response, such as the type of data (Content-Type) or how long it is (Content-Length). They help the client know how to handle the response body.

Result

You understand that headers are key-value pairs sent before the actual data to describe or control the response.

Knowing that headers are separate from the main data helps you see how servers communicate extra instructions without changing the content.

2

Foundation

Basics of Spring Boot response handling

Concept: Learn how Spring Boot sends responses and where headers fit in.

Spring Boot uses controllers to handle web requests. When a controller method returns data, Spring Boot builds an HTTP response with status, headers, and body. By default, Spring Boot adds standard headers like Content-Type automatically based on the data returned.

Result

You see that Spring Boot manages response creation and headers behind the scenes, but you can customize them.

Understanding Spring Boot's response flow prepares you to add or change headers explicitly.

3

Intermediate

Adding custom headers with ResponseEntity

🤔Before reading on: do you think you can add headers by just returning a string from a controller? Commit to your answer.

Concept: Learn how to use ResponseEntity to add custom headers to responses.

ResponseEntity is a Spring Boot class that lets you build responses with full control. You can set status, headers, and body explicitly. To add a custom header, create a ResponseEntity, add headers using HttpHeaders, and return it from your controller method. Example: @GetMapping("/hello") public ResponseEntity hello() { HttpHeaders headers = new HttpHeaders(); headers.add("X-Custom-Header", "MyValue"); return new ResponseEntity<>("Hello World", headers, HttpStatus.OK); }

Result

The client receives the response with the custom header 'X-Custom-Header: MyValue' along with the body 'Hello World'.

Knowing ResponseEntity lets you fully customize responses, including headers, status, and body, unlocking flexible server-client communication.

4

Intermediate

Using @ResponseHeader annotation for simple headers

🤔Before reading on: do you think Spring Boot has a shortcut to add headers without building ResponseEntity? Commit to your answer.

Concept: Learn about the @ResponseHeader annotation to add headers easily in some cases.

Spring Boot supports adding headers directly using the @ResponseHeader annotation on controller methods. This is useful for simple static headers. Example: @GetMapping("/info") @ResponseHeader(name = "X-App-Version", value = "1.0") public String info() { return "App Info"; } Note: This annotation is less flexible and mainly for fixed headers.

Result

The response includes the header 'X-App-Version: 1.0' automatically.

Knowing this shortcut helps you add simple headers quickly without extra code, but it is limited compared to ResponseEntity.

5

Intermediate

Adding headers with HttpServletResponse object

🤔Before reading on: do you think you can add headers by directly modifying the response object? Commit to your answer.

Concept: Learn how to add headers by accessing the raw HttpServletResponse in controller methods.

Spring Boot lets you access the HttpServletResponse object directly as a method parameter. You can call response.addHeader(name, value) to add headers. Example: @GetMapping("/direct") public String direct(HttpServletResponse response) { response.addHeader("X-Direct-Header", "DirectValue"); return "Direct Response"; }

Result

The client receives the response with the custom header 'X-Direct-Header: DirectValue'.

Understanding direct response manipulation gives you low-level control but can mix concerns and is less declarative.

6

Advanced

Using filters to add headers globally

🤔Before reading on: do you think you can add headers to every response automatically? Commit to your answer.

Concept: Learn how to use Spring Boot filters to add headers to all responses in one place.

Filters are components that run before or after requests reach controllers. You can create a filter to add headers to every response automatically. Example: @Component public class CustomHeaderFilter implements Filter { @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletResponse httpResp = (HttpServletResponse) response; httpResp.addHeader("X-Global-Header", "GlobalValue"); chain.doFilter(request, response); } }

Result

Every HTTP response from your app includes the header 'X-Global-Header: GlobalValue'.

Knowing filters lets you apply headers consistently across your app without changing each controller.

7

Expert

Handling header conflicts and ordering

🤔Before reading on: if multiple parts add the same header, do you think Spring Boot merges, overwrites, or duplicates them? Commit to your answer.

Concept: Learn how Spring Boot and the underlying server handle multiple headers with the same name and the order of header application.

When multiple components add the same header, Spring Boot and the servlet container may merge or overwrite headers depending on how they are added. For example, HttpHeaders in ResponseEntity replaces headers with the same name, while response.addHeader() adds duplicates. Filters run before controllers, so headers added in filters appear first. Understanding this helps avoid unexpected header values or duplicates. Best practice is to centralize header management to prevent conflicts.

Result

You avoid bugs where clients receive multiple or conflicting headers, ensuring predictable behavior.

Understanding header merging and order prevents subtle bugs in production where headers behave differently than expected.

Under the Hood

When a Spring Boot app handles a web request, it uses the embedded servlet container (like Tomcat) to build an HTTP response. The response has a header section and a body. Headers are stored in a map-like structure. When you add custom headers via ResponseEntity or HttpServletResponse, Spring adds these key-value pairs to the response header map. Before sending, the server serializes headers into text lines. Filters and interceptors can modify headers before the response is finalized. The order of these modifications affects the final headers sent to the client.

Why designed this way?

HTTP was designed as a text-based protocol with headers separated from the body to allow flexible metadata exchange. Spring Boot builds on this by providing multiple ways to add headers to fit different developer needs: declarative (ResponseEntity), imperative (HttpServletResponse), and global (filters). This layered design balances ease of use, flexibility, and control. Alternatives like forcing one method would limit use cases or complicate simple tasks.

┌───────────────┐
│ Client Request│
└──────┬────────┘
       │
┌──────▼────────┐
│ Spring Boot   │
│ Controller    │
│ (builds body) │
└──────┬────────┘
       │
┌──────▼────────┐
│ ResponseEntity│
│ or HttpServlet│
│ Response      │
└──────┬────────┘
       │
┌──────▼────────┐
│ Filters/Inter-│
│ ceptors      │
└──────┬────────┘
       │
┌──────▼────────┐
│ Servlet       │
│ Container     │
│ (Tomcat)      │
└──────┬────────┘
       │
┌──────▼────────┐
│ HTTP Response │
│ Headers + Body│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: If you add the same header twice using ResponseEntity, will both appear or only one? Commit to your answer.

Common Belief: Adding the same header twice always results in both headers being sent to the client.

Reality: ResponseEntity's HttpHeaders replaces headers with the same name, so only the last value is sent, not duplicates.

Why it matters: Assuming duplicates appear can cause bugs where clients miss expected header values or behave incorrectly.

Quick: Does adding headers via HttpServletResponse always override headers set by ResponseEntity? Commit to your answer.

Common Belief: Headers added via HttpServletResponse always override those set by ResponseEntity.

Reality: Headers added via HttpServletResponse are added directly to the response and can coexist with ResponseEntity headers, potentially causing duplicates or conflicts.

Why it matters: Misunderstanding this can lead to unexpected header duplication or ordering issues, confusing clients.

Quick: Can you add custom headers after the response body is committed? Commit to your answer.

Common Belief: You can add or modify headers at any time before the response is sent to the client.

Reality: Once the response body starts sending (committed), headers cannot be changed; attempts to do so are ignored or cause errors.

Why it matters: Trying to add headers too late leads to silent failures and missing headers in responses.

Quick: Are custom headers visible in browser developer tools by default? Commit to your answer.

Common Belief: All custom headers sent by the server are always visible in browser developer tools.

Reality: Some headers may be hidden or filtered by browsers or proxies; also, CORS policies can block access to certain headers in client-side scripts.

Why it matters: Assuming headers are always visible can mislead debugging and testing efforts.

Expert Zone

1

Headers added in filters run before controllers, so they appear earlier in the response and can be overwritten by later code.

2

Using ResponseEntity allows immutable headers, which helps avoid accidental changes later in the response lifecycle.

3

Some headers like 'Set-Cookie' require special handling to avoid security issues; blindly adding them can cause vulnerabilities.

When NOT to use

Custom response headers are not suitable for sending large or sensitive data; use response body or secure tokens instead. For complex cross-origin resource sharing, use dedicated CORS configuration rather than manual headers. Avoid adding headers in multiple places to prevent conflicts; centralize header management.

Production Patterns

In production, custom headers are used for versioning (e.g., X-App-Version), security policies (e.g., Content-Security-Policy), caching controls (e.g., Cache-Control), and tracing (e.g., X-Request-ID). Filters or interceptors often add these headers globally. ResponseEntity is used for endpoint-specific headers, especially in REST APIs.

Connections

HTTP Protocol

Custom response headers build directly on the HTTP protocol's header mechanism.

Understanding HTTP headers deeply helps you use custom headers effectively and troubleshoot communication issues.

Web Security

Custom headers are often used to implement security policies like CORS, CSP, and HSTS.

Knowing how headers affect security helps you protect applications from attacks like cross-site scripting and clickjacking.

Supply Chain Management

Both use labels or tags to communicate handling instructions along a chain.

Seeing custom headers as labels in a supply chain clarifies their role in guiding data handling across systems.

Common Pitfalls

#1 Adding headers after response body is committed

Wrong approach:

response.getWriter().write("data");
response.addHeader("X-Late-Header", "value");

Correct approach:

response.addHeader("X-Late-Header", "value");
response.getWriter().write("data");

Root cause:

Headers must be set before the response body starts sending; otherwise, they are ignored.

#2 Adding duplicate headers unintentionally

Wrong approach:

response.addHeader("X-Dup", "one");
response.addHeader("X-Dup", "two");

Correct approach:

response.setHeader("X-Dup", "two");

Root cause:

Using addHeader adds duplicates; setHeader replaces existing header values.

#3 Mixing ResponseEntity and HttpServletResponse header setting

Wrong approach:

return new ResponseEntity<>(body, headers, status);
// and also
response.addHeader("X-Conflicting", "value");

Correct approach:

Choose one method to set headers consistently, preferably ResponseEntity for clarity.

Root cause:

Using both methods can cause conflicts and unpredictable header results.

Key Takeaways

Custom response headers let servers send extra instructions or info alongside response data.

Spring Boot offers multiple ways to add headers: ResponseEntity, HttpServletResponse, annotations, and filters.

Understanding when and how headers are added prevents bugs like duplicates or missing headers.

Filters allow adding headers globally, while ResponseEntity offers fine control per response.

Headers must be set before the response body is sent; otherwise, changes are ignored.