Content Negotiation With Accept Headers: A YJTOON Tour

YJTOON serves three formats. Most clients do not want to think about which one they get. Content negotiation is the smallest interface that gives them the right answer.

The short version

• Accept: application/toon → TOON
• Accept: application/yaml → YAML
• Accept: application/json → JSON
• Anything else → JSON (the safe default)

Quality values

We honor q=. Accept: application/json;q=0.9, application/toon;q=0.7 means JSON preferred, TOON acceptable, YAML not on the list.

The ?format= override

Sometimes the Accept header is set by a library you do not control. Append ?format=toon to the URL to force a format. The override wins.

Why this design

Most APIs pick one format and call it done. YJTOON is a reference data project, so the format choice is part of the value. Content negotiation lets the client pick without growing the URL space.