Dev.to WebDev 🛠 Dev 👁 0 📖 4 min read

OpenAPI Content Negotiation with Accept

Quick answer: Content negotiation lets one URL return different formats: the client sends an Accept header listing the media types it can handle with q-value priorities, and the server picks one it supports and reports i

Quick answer: Content negotiation lets one URL return different formats: the client sends an Accept header listing the media types it can handle with q-value priorities, and the server picks one it supports and reports it in Content-Type. In OpenAPI you document this by listing multiple media types under a response's content object, and you add a 406 response for when none match. The spec describes what the server can produce; the actual selection logic still lives in your server code.

How Accept negotiation works

The Accept header is a ranked list of media types, not a single demand. A value such as application/json, application/xml;q=0.9, */*;q=0.5 says the client prefers JSON, accepts XML at a slightly lower priority, and will take anything else as a last resort. The q factor ranges from 0 to 1 and defaults to 1 when omitted, so a type without a q value ranks highest.

A type can be specific, like application/json, use a subtype wildcard such as application/*, or use the full wildcard */*. The server compares this list against the representations it can produce, selects the best match, and returns it with a Content-Type header stating what came back. The same resource URL then serves JSON to one client and XML to another without a separate endpoint.

Describing multiple types in OpenAPI

In an OpenAPI document, the content object under a response holds one entry per supported media type. Each entry points at a schema, and one schema can back several formats. A requestBody works the same way, listing the types a client may send.

The OpenAPI guide keeps this at the response level rather than inventing a separate operation per format. Here is how the pieces line up.

Piece Where it appears What it controls
Accept Request header Types the client will accept
content Response or requestBody Types the operation documents
Content-Type Response header The type actually returned
406 Responses No offered type was acceptable

You can also declare Accept as an explicit header parameter to document allowed values, but for ordinary cases the response content already shows which types the server produces.

How the server picks a response

Selection follows the ranked Accept list and the server's available representations. When the highest-priority type is one the server can produce, that type wins. If nothing in the list matches, the server returns 406 Not Acceptable, which is why a well-formed document lists a 406 response alongside the success codes.

When the client sends no Accept header, the server falls back to a configured default, often application/json. State that default in the description so the behavior is not guessed. The OpenAPI file never performs this matching; it records the contract, and the framework or application code must implement the ranking and the 406 path.

JSON and XML mapping notes

JSON and XML frequently represent the same domain model, but they do not map one to one. XML has no native array or object, so a list of items may need a wrapper element, and a field may be rendered as an attribute rather than an element. OpenAPI provides an xml object with name, wrapped, and attribute settings to express those differences against a shared schema.

Verify the mapping rather than assuming the XML serializer follows the JSON shape. After documenting multiple media types in Powerduck, send real requests with different Accept values and check the returned Content-Type and body structure, including a request that forces the 406 path, so the documented formats match what the server emits.

Common mistakes

The most frequent gap is documenting only application/json while clients expect XML, or the reverse, where the server returns a type the spec never lists. Another is omitting 406 and leaving clients with an undocumented error. A Content-Type response that does not match the declared media type breaks generators that rely on it.

Do not confuse format negotiation with version negotiation. A vendor type such as application/vnd.acme.v2+json folds a version into the media type and is a separate governance choice, not just another output format. Finally, treat q values as ordering hints, not exact percentages, and make sure the default for a missing Accept header is written down.

Frequently asked questions

Do I need a separate endpoint for each format? No, one operation lists several media types under content, and the Accept header selects among them.

What does q mean? It is a relative priority from 0 to 1, where a higher value is preferred and 1 is the default.

When should I return 406? When the server cannot produce any media type the client listed in Accept.

Is Accept the same as Content-Type? No, Accept states what the client wants back, while Content-Type states what is actually in the response or request body.

The bottom line

Use the Accept header to serve multiple representations from one URL and document each one under the response content object, with a 406 response for unmatched requests. Remember the spec only records the contract; the server still has to rank the offered types and apply a default when Accept is absent. Check JSON and XML mapping against a shared schema, and verify every format with a real request so the documented media types match the live behavior.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.