CORS Configuration & Content Negotiation

Two things that seem trivial until they silently break your entire frontend-backend integration: CORS and content type resolution.

CORS (Cross-Origin Resource Sharing)

What Is CORS?

Browsers enforce the Same-Origin Policy: JavaScript on app.example.com cannot call api.example.com unless the server explicitly allows it via CORS headers.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
sequenceDiagram
    participant Browser
    participant Frontend as Frontend<br/>app.example.com
    participant Backend as Backend<br/>api.example.com

    Frontend->>Browser: fetch('/api/users')
    Note over Browser: Different origin detected
    Browser->>Backend: OPTIONS /api/users<br/>Origin: app.example.com<br/>Access-Control-Request-Method: GET
    Backend->>Browser: 200 OK<br/>Access-Control-Allow-Origin: app.example.com<br/>Access-Control-Allow-Methods: GET,POST
    Note over Browser: Preflight passed
    Browser->>Backend: GET /api/users<br/>Origin: app.example.com
    Backend->>Browser: 200 OK + JSON payload
    Browser->>Frontend: Response data

@CrossOrigin Annotation

The quickest way to enable CORS for a specific endpoint or controller.

@RestController
@RequestMapping("/api/users")
public class UserController {

    @CrossOrigin(origins = "https://app.example.com")
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

@CrossOrigin(
    origins = {"https://app.example.com", "https://admin.example.com"},
    methods = {RequestMethod.GET, RequestMethod.POST, RequestMethod.PUT},
    allowedHeaders = {"Authorization", "Content-Type"},
    exposedHeaders = {"X-Total-Count"},
    allowCredentials = "true",
    maxAge = 3600
)
@RestController
@RequestMapping("/api/orders")
public class OrderController {
    // All endpoints inherit CORS config
}

Global CORS via WebMvcConfigurer

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
            .allowedOrigins("https://app.example.com", "https://admin.example.com")
            .allowedMethods("GET", "POST", "PUT", "DELETE", "PATCH")
            .allowedHeaders("*")
            .exposedHeaders("X-Total-Count", "X-Page-Number")
            .allowCredentials(true)
            .maxAge(3600);

        // Separate config for public endpoints
        registry.addMapping("/public/**")
            .allowedOrigins("*")
            .allowedMethods("GET")
            .maxAge(86400);
    }
}

CorsFilter for Spring Security Integration

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart LR
    REQ["Incoming<br/>Request"]
    CF["CorsFilter"]
    SF["Security<br/>FilterChain"]
    DS["Dispatcher<br/>Servlet"]
    CTRL["Controller"]

    REQ --> CF
    CF -->|"Preflight? Respond 200"| RESP["200 OK +<br/>CORS Headers"]
    CF -->|"Actual request"| SF
    SF --> DS
    DS --> CTRL

    style REQ fill:#EFF6FF,stroke:#93C5FD,color:#1E40AF
    style CF fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style SF fill:#FEF3C7,stroke:#FCD34D,color:#92400E
    style DS fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style CTRL fill:#ECFDF5,stroke:#6EE7B7,color:#065F46
    style RESP fill:#D1FAE5,stroke:#6EE7B7,color:#065F46

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // Enable CORS with the bean defined below
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**").permitAll()
                .anyRequest().authenticated()
            );
        return http.build();
    }

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOrigins(List.of(
            "https://app.example.com",
            "https://admin.example.com"
        ));
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"));
        config.setAllowedHeaders(List.of("*"));
        config.setExposedHeaders(List.of("X-Total-Count"));
        config.setAllowCredentials(true);
        config.setMaxAge(3600L);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/api/**", config);
        return source;
    }
}

CORS Configuration Properties

Common CORS Mistakes

// THIS WILL FAIL at runtime
config.setAllowedOrigins(List.of("*"));
config.setAllowCredentials(true);

// OPTIONS never reaches the CORS filter
http.authorizeHttpRequests(auth -> auth
    .anyRequest().authenticated()  // blocks OPTIONS too!
);

.requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()

Content Negotiation

How Spring Resolves Response Format

When a client sends a request, Spring must decide which format to serialize the response into. It uses a strategy chain:

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart TD
    REQ["Client Request"]
    S1["Strategy 1:<br/>Accept Header"]
    S2["Strategy 2:<br/>URL Path Ext."]
    S3["Strategy 3:<br/>Query Param<br/>(?format=json)"]
    S4["Default:<br/>application/json"]
    CONV["Select<br/>MessageConverter"]
    RESP["Serialized<br/>Response"]

    REQ --> S1
    S1 -->|"Not determined"| S2
    S1 -->|"Resolved"| CONV
    S2 -->|"Not determined"| S3
    S2 -->|"Resolved"| CONV
    S3 -->|"Not determined"| S4
    S3 -->|"Resolved"| CONV
    S4 --> CONV
    CONV --> RESP

    style REQ fill:#EFF6FF,stroke:#93C5FD,color:#1E40AF
    style S1 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style S2 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style S3 fill:#FEF3C7,stroke:#FCD34D,color:#92400E
    style S4 fill:#FEE2E2,stroke:#FCA5A5,color:#991B1B
    style CONV fill:#ECFDF5,stroke:#6EE7B7,color:#065F46
    style RESP fill:#EFF6FF,stroke:#93C5FD,color:#1E40AF

ContentNegotiationConfigurer

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer
            // Honor the Accept header
            .favorParameter(true)           // Enable ?format=json
            .parameterName("format")
            .ignoreAcceptHeader(false)
            // Default to JSON if nothing specified
            .defaultContentType(MediaType.APPLICATION_JSON)
            // Map format parameter values to media types
            .mediaType("json", MediaType.APPLICATION_JSON)
            .mediaType("xml", MediaType.APPLICATION_XML)
            .mediaType("csv", MediaType.valueOf("text/csv"));
    }
}

Producing Specific Media Types

Use produces in @RequestMapping to restrict what formats an endpoint can return:

@RestController
@RequestMapping("/api/reports")
public class ReportController {

    // Only returns JSON
    @GetMapping(value = "/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
    public Report getReportJson(@PathVariable Long id) {
        return reportService.findById(id);
    }

    // Only returns XML
    @GetMapping(value = "/{id}", produces = MediaType.APPLICATION_XML_VALUE)
    public Report getReportXml(@PathVariable Long id) {
        return reportService.findById(id);
    }

    // Returns CSV (custom media type)
    @GetMapping(value = "/{id}/export", produces = "text/csv")
    public ResponseEntity<String> exportCsv(@PathVariable Long id) {
        String csv = reportService.toCsv(id);
        return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=report.csv")
            .body(csv);
    }
}

@PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE, 
             produces = MediaType.APPLICATION_JSON_VALUE)
public User createUser(@RequestBody User user) { ... }

HttpMessageConverter Selection

Spring uses HttpMessageConverter implementations to serialize/deserialize request/response bodies. The converter is selected based on the media type resolved by content negotiation.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '13px', 'fontFamily': 'Inter, -apple-system, sans-serif'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 50, 'padding': 12, 'curve': 'basis'}, 'sequence': {'actorMargin': 60, 'messageMargin': 40}, 'class': {'padding': 12}}}%%
flowchart LR
    CT["Content-Type<br/>resolved"]
    MC1["Jackson<br/>JSON Converter"]
    MC2["JAXB<br/>XML Converter"]
    MC3["StringHttp<br/>Converter"]
    MC4["Custom<br/>CSV Converter"]
    OUT["Response<br/>Body"]

    CT -->|"application/json"| MC1
    CT -->|"application/xml"| MC2
    CT -->|"text/plain"| MC3
    CT -->|"text/csv"| MC4
    MC1 --> OUT
    MC2 --> OUT
    MC3 --> OUT
    MC4 --> OUT

    style CT fill:#FEF3C7,stroke:#FCD34D,color:#92400E
    style MC1 fill:#DBEAFE,stroke:#93C5FD,color:#1E40AF
    style MC2 fill:#D1FAE5,stroke:#6EE7B7,color:#065F46
    style MC3 fill:#EFF6FF,stroke:#93C5FD,color:#1E40AF
    style MC4 fill:#FFFBEB,stroke:#FCD34D,color:#92400E
    style OUT fill:#ECFDF5,stroke:#6EE7B7,color:#065F46

Built-in Converters (ordered by priority):

Custom MediaType & MessageConverter

// 1. Define a custom media type
public class CustomMediaTypes {
    public static final String CSV_VALUE = "text/csv";
    public static final MediaType CSV = MediaType.valueOf(CSV_VALUE);
}

// 2. Implement a custom converter
public class CsvHttpMessageConverter extends AbstractHttpMessageConverter<List<?>> {

    public CsvHttpMessageConverter() {
        super(CustomMediaTypes.CSV);
    }

    @Override
    protected boolean supports(Class<?> clazz) {
        return List.class.isAssignableFrom(clazz);
    }

    @Override
    protected List<?> readInternal(Class<? extends List<?>> clazz,
                                    HttpInputMessage inputMessage) {
        // Parse CSV to list of objects
        throw new UnsupportedOperationException("CSV read not supported");
    }

    @Override
    protected void writeInternal(List<?> objects,
                                  HttpOutputMessage outputMessage) throws IOException {
        OutputStreamWriter writer = new OutputStreamWriter(outputMessage.getBody());
        // Write header row
        // Write data rows using reflection or known structure
        for (Object obj : objects) {
            writer.write(toCsvRow(obj));
            writer.write("\n");
        }
        writer.flush();
    }

    private String toCsvRow(Object obj) {
        // Convert object fields to CSV row
        return obj.toString(); // simplified
    }
}

// 3. Register the converter
@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        converters.add(new CsvHttpMessageConverter());
    }
}

Quick Recall

Interview Template