How to perform content negotiation?

[drauschenbach]

I can't seem to figure out how to examine an accept header. There are various references to the Accept header name in the code, and some wildcard matching functionality in accept.rs, but no examples. Is there an extractor? The Either handler example is somewhat contrived in that it does not attempt to examine an Accept header.

[sunnypatell]

@drauschenbach actix-web has a typed Accept header you can extract directly with web::Header<Accept>:

use actix_web::{get, web, HttpResponse};
use actix_web::http::header::{Accept, ContentType};

#[get("/resource")]
async fn handler(accept: web::Header<Accept>) -> HttpResponse {
    let data = serde_json::json!({"key": "value"});

    // preference() returns the highest-q mime type
    let preferred = accept.preference();

    if preferred == mime::APPLICATION_JSON || preferred == mime::STAR_STAR {
        HttpResponse::Ok().content_type(ContentType::json()).json(&data)
    } else if preferred == mime::TEXT_HTML {
        HttpResponse::Ok().content_type(ContentType::html()).body("<h1>value</h1>")
    } else {
        HttpResponse::NotAcceptable().finish()
    }
}

for proper server-driven negotiation (walking the full q-factor list), use ranked() instead of preference(). ranked() returns all mimes sorted by quality descending with specificity tiebreaking (text/html > text/* > */*):

fn negotiate(accept: &Accept, supported: &[mime::Mime]) -> Option<mime::Mime> {
    for requested in accept.ranked() {
        for s in supported {
            if requested == *s
                || (requested.type_() == s.type_() && requested.subtype() == mime::STAR)
                || requested == mime::STAR_STAR
            {
                return Some(s.clone());
            }
        }
    }
    None
}

note: Accept derefs to Vec<QualityItem<Mime>> so you can also .iter() over individual items and inspect qi.item / qi.quality directly. there's no built-in negotiate() method on Accept yet (there's a TODO in the source), unlike AcceptEncoding which has one.

wrap in Option<web::Header<Accept>> if you want graceful fallback when the header is missing instead of a 400.

ref: Accept docs | web::Header extractor | QualityItem

[drauschenbach]

Thanks! That's super helpful.

I still don't understand why the Accept docs show a server responding with an Accept header. When does that ever occur??? I thought clients set that header, and servers respond with Content-Type.

[sunnypatell]

@drauschenbach you're right, that's a misleading doc example. the source code shows HttpResponse::Ok().insert_header(Accept(...)) which puts an Accept header on a response, but Accept is a request header per RFC 7231 §5.3.2.

it's just a lazy doc example demonstrating how to construct the type, not showing actual usage. the common_header! macro generates all the header types with the same pattern and the examples just show "here's how to build this struct" rather than where it belongs in a real request/response flow.

a server can technically send Accept in a response in one edge case: HTTP OPTIONS responses (to indicate what content types the endpoint accepts), but that's via the Accept header in a 406 Not Acceptable response or informational response per RFC 7231 §6.5.6. in practice almost nobody does this.

for your use case, you'd only ever extract it from requests like in my example above with web::Header<Accept>.

[drauschenbach]

Again, thanks for the thorough reply. I'm glad we cleared this up, for myself and for whomever else might need to find these breadcrumbs in the future.

[JohnTitor]

I still don't understand why the Accept docs show a server responding with an Accept header. When does that ever occur??? I thought clients set that header, and servers respond with Content-Type.

you're right, that's a misleading doc example. the source code shows HttpResponse::Ok().insert_header(Accept(...)) which puts an Accept header on a response, but Accept is a request header per RFC 7231 §5.3.2.

Sorry for the trouble!
Indeed it's misleading so I've improved docs and examples for req headers: #3921
Hope this would make sense!

[sunnypatell]

nice, that PR looks solid. should save people the same "wait why is this on a response" confusion going forward. thanks for the quick turnaround @JohnTitor!