application/vnd.api+json

API Design

Meaning

The IANA-registered MIME type for the JSON:API specification, used in HTTP Content-Type and Accept headers to signal that request and response bodies follow the JSON:API document format. It eliminates ambiguity about which JSON dialect is being exchanged, preventing clients from misparsing server payloads or servers from rejecting well-formed JSON:API requests. Reached for whenever a service implements or consumes the JSON:API standard and needs to negotiate the wire format over HTTP.

Primary Function

Content type negotiation

Communicative Purpose

Ensures clients and servers agree on the JSON:API wire format during HTTP content negotiation.

Pattern

Content-Type: application/vnd.api+json (response) | Accept: application/vnd.api+json (request)

Função primária

Content type negotiation

Propósito comunicativo

Ensures clients and servers agree on the JSON:API wire format during HTTP content negotiation.

Situações de gatilho

REST API design: setting the Content-Type header on a JSON:API response; API client: sending Accept: application/vnd.api+json to request JSON:API-formatted resources; API gateway: routing or validating requests based on the declared media type.

Contextos

JSON:API specification, RESTful web services, HTTP API design, content negotiation, OpenAPI-documented APIs.

Padrão

Content-Type: application/vnd.api+json (response) | Accept: application/vnd.api+json (request)

Colocados típicos

Content-Type header
Accept header
JSON:API document structure
resource objects
relationships object
links object.

Substituições comuns

application/json — loses JSON:API conformance signaling
application/hal+json — uses HAL hypermedia format instead
application/jsonapi+json — older non-standard variant
not IANA-registered.

Erros comuns

Using application/jsonapi+json instead of the registered +json suffix — servers may reject requests as unsupported media type. Omitting the +json structured syntax suffix — breaks content negotiation rules per RFC 6838. Setting the header only on responses but not on Accept in clients — prevents content negotiation from working. Treating the MIME type as optional decoration — strict JSON:API servers reject mismatched Content-Type. Confusing it with application/ld+json (JSON-LD) — different hypermedia formats with different document structures.

Similar / contraste

application/hal+json — HAL hypermedia format; application/ld+json — JSON-LD for linked data; application/problem+json — RFC 7807 error responses; application/json — generic JSON without a specific dialect.

Interferências

Coming from generic REST: may assume application/json is sufficient — JSON:API requires the vendor-specific +json suffix to signal dialect. Coming from SOAP/XML: may expect a namespace URI in the type — MIME types use the vendor tree (vnd.) instead of XML namespaces.

Família do chunk

JSON:API specification
content negotiation
MIME type design
hypermedia formats (HAL
JSON-LD
Siren).

Nuance

When NOT to use: avoid for non-JSON:API endpoints or when the API does not follow the JSON:API document structure (resources, relationships, links). Performance: no measurable overhead beyond the header bytes. Boundary condition: the +json suffix is mandatory per RFC 6838 structured syntax suffix rules — omitting it makes the type technically invalid.

Efeito pragmático

Correctly setting this header enables strict JSON:API servers to accept and validate payloads, and lets generic API tooling auto-detect the dialect for deserialization, link traversal, and relationship expansion.

Dica de memória

Think of it as a dialect passport stamped on every JSON:API envelope — without it, servers can't tell JSON:API apart from plain JSON at the door.

Nota

Registered with IANA as the official media type for the JSON:API specification (https://jsonapi.org).

Upgrade path

JSON:API compound documents, sparse fieldsets, and relationship inclusion via ?include= query parameters.

Frequência: MediumFormulaicidade: Fully fixedPrioridade de aquisição: Recognition firstPrioridade de output: BothTag de espaçamento: Long-term

Examples

from flask import Flask, jsonify app = Flask(__name__) @app.route('/articles/1') def get_article(): payload = { "data": { "type": "article", "id": "1", "attributes": {"title": "JSON:API in practice"} } } response = jsonify(payload) response.headers['Content-Type'] = 'application/vnd.api+json' return response

import requests headers = { 'Accept': 'application/vnd.api+json', 'Content-Type': 'application/vnd.api+json' } response = requests.post( 'https://api.example.com/articles', headers=headers, json={ "data": { "type": "article", "attributes": {"title": "New post"} } } ) print(response.json())

// Express.js middleware that enforces JSON:API content negotiation app.use((req, res, next) => { if (req.method === 'POST' || req.method === 'PATCH') { const contentType = req.headers['content-type'] || ''; if (!contentType.includes('application/vnd.api+json')) { return res.status(415).json({ errors: [{ status: '415', title: 'Unsupported Media Type', detail: 'Content-Type must be application/vnd.api+json' }] }); } } res.setHeader('Content-Type', 'application/vnd.api+json'); next(); });