HTTP authoring guides

Set media preferences with an Accept header

·

An API client can prefer a custom representation and still accept ordinary JSON as a fallback. The workshop draft shows those two choices and an explicit exclusion while keeping a comma inside a quoted parameter.

Request Header Builder

Build the workshop client’s three media ranges

Load the example, then select Build headers. The first media range is application/vnd.workshop+json with a quoted profile parameter. Its q value of 1 uses the default weight, so the generated range has no q parameter.

The comma inside the profile value remains inside its quotation marks. The next ranges are application/json with q=0.65 and text/* with q=0. These describe an acceptable fallback and a range that is unacceptable.

Accept header from the worked example
Accept: application/vnd.workshop+json;profile="https://docs.example.invalid/agenda,compact", application/json;q=0.65, text/*;q=0

RFC 9110 — AcceptRFC 9110 — Quality values in content negotiation

Check the field lines and JSON order

In Text output, the generated Accept line precedes X-Workshop-View and Accept-Language from the draft. Download text to save those three field lines with CRLF endings.

Switch Output format to JSON or select Download JSON. The headers array stores an object for each field in the same order, which lets a test fixture keep repeated lines separate.

RFC 9110 — Field names and order

Correct a malformed preference

Set Quality 2 to 0.6501 and try Build headers. The tool identifies Accept row 2 because the value exceeds three decimal places. Change it to 0.65 and rebuild.

If a draft requires only custom headers, remove or leave empty the media-range rows. Put any general field on its own line, using its field name, a colon and its value.

RFC 9110 — Quality values in content negotiation

Common questions

Does the list determine what a server must return?

It states the client’s preferences. Check the target API’s negotiation behavior and supported representations to learn what it returns.

Can I include a media parameter with spaces?

Use a quoted value. The builder rejects unclosed quotes and repeated parameter names within one range.

Sources

Put it into practice.

Related guides