Content Negotiation & Output Formatters

// Client request: Accept: application/xml
[HttpGet("{id}")]
public ActionResult<Product> GetProduct(int id) => Ok(_service.GetById(id));
// Returns XML instead of the default JSON if an XML formatter is registered and requested

Common follow-ups: What happens if the requested format isn't supported by any registered formatter?;How do you force a specific format regardless of the Accept header?

builder.Services.AddControllers()
    .AddXmlSerializerFormatters();

// Now both of these work automatically:
// GET /api/products/1  Accept: application/json  -> JSON response
// GET /api/products/1  Accept: application/xml   -> XML response

Common follow-ups: What are the performance and complexity trade-offs of supporting multiple output formats?;How does XML serialization handle types that don't map cleanly to XML, like dictionaries?

public class CsvOutputFormatter : TextOutputFormatter {
    public CsvOutputFormatter() {
        SupportedMediaTypes.Add("text/csv");
        SupportedEncodings.Add(Encoding.UTF8);
    }
    protected override bool CanWriteType(Type type) => typeof(IEnumerable<Product>).IsAssignableFrom(type);
    public override async Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding encoding) {
        var products = (IEnumerable<Product>)context.Object;
        var csv = string.Join("\n", products.Select(p => $"{p.Id},{p.Name},{p.Price}"));
        await context.HttpContext.Response.WriteAsync(csv, encoding);
    }
}

Common follow-ups: How does a custom formatter interact with Swagger documentation generation for the extra format?;What's the difference between TextOutputFormatter and the lower-level OutputFormatter base class?

// Accept: application/xml;q=0.9, application/json;q=0.8
// If both XML and JSON formatters are registered, XML wins due to higher q-value

// Accept: application/pdf
// If no PDF formatter is registered: either falls back to default, or returns 406

Common follow-ups: What does RespectBrowserAcceptHeader configuration control, and why is it off by default?;How do you configure the API to return 406 instead of silently falling back to a default format?

// Browser navigating directly to /api/products sends:
// Accept: text/html, application/xhtml+xml, ...

// With RespectBrowserAcceptHeader = false (default):
// API still returns JSON, ignoring the browser's HTML preference

// With RespectBrowserAcceptHeader = true:
// API might return 406 or attempt HTML formatting, which is rarely desired for a pure API

Common follow-ups: When would you actually want to enable RespectBrowserAcceptHeader?;How does this interact with an API that also serves some HTML content, like Swagger UI?

builder.Services.AddControllers()
    .AddJsonOptions(options => {
        options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
        options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
    });

Common follow-ups: How do these global options interact with per-property [JsonPropertyName] attributes?;What's the performance cost of adding custom converters to every serialization?

[HttpGet("{id}")]
[Produces("application/vnd.myapp.v1+json", "application/vnd.myapp.v2+json")]
public IActionResult GetProduct(int id) {
    var acceptHeader = Request.Headers.Accept.ToString();
    return acceptHeader.Contains("v2")
        ? Ok(MapToV2(product))
        : Ok(MapToV1(product));
}

Common follow-ups: Why is media-type versioning less commonly adopted in practice than URL or header versioning?;How would you document this versioning approach clearly in OpenAPI/Swagger?

[Produces("application/json")]
[HttpPost("webhook")]
public IActionResult ReceiveWebhook(WebhookPayload payload) {
    // Always returns JSON, even if the caller's Accept header requested XML
    return Ok(new { received = true });
}

Common follow-ups: How does [Produces] interact with content negotiation for the request body versus the response?;What's the difference between [Produces] at the controller level versus the action level?

// Client sends Content-Type: application/json with a JSON body -- input formatter deserializes it
[HttpPost]
public IActionResult CreateProduct([FromBody] ProductDto dto) { ... }

// Client sends Content-Type: application/xml but no XML input formatter registered:
// -> 415 Unsupported Media Type, action never executes

Common follow-ups: What's the difference between 415 (wrong Content-Type) and 400 (malformed body of the correct type)?;How would you add a custom input formatter for a non-standard request format?

app.MapGet("/products/{id}", (int id, HttpContext context) => {
    var product = GetProduct(id);
    if (context.Request.Headers.Accept.ToString().Contains("xml")) {
        return Results.Text(SerializeToXml(product), "application/xml");
    }
    return Results.Json(product);
});

Common follow-ups: Why did minimal APIs deprioritize built-in multi-format negotiation compared to MVC?;How would you build a reusable helper for this manual negotiation pattern across many minimal API endpoints?