Which JSON content type do I use?

Choosing the Right JSON Content Type (MIME Type)

Understand the nuances of JSON MIME types, including application/json and application/vnd.api+json, and when to use each for robust API communication.

When working with web APIs and data exchange, JSON (JavaScript Object Notation) has become the de facto standard. However, simply sending JSON data isn't always enough; specifying the correct Content-Type header is crucial for proper interpretation by clients and servers. This article delves into the primary JSON MIME types, their use cases, and best practices for their implementation.

The Standard: application/json

The most common and widely accepted MIME type for JSON data is application/json. This type indicates that the body of an HTTP request or response contains a JSON-formatted data structure. It's defined in RFC 8259 (which obsoletes RFC 4627) and is the default choice for almost all general-purpose JSON communication.

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 30

{"name": "Alice", "age": 30}

Example HTTP POST request with Content-Type: application/json.

Specialized JSON: application/vnd.api+json (JSON:API)

Beyond the generic application/json, there are more specialized JSON media types designed for specific API specifications. One prominent example is application/vnd.api+json, which is used by the JSON:API specification. JSON:API is a standard for building APIs that aims to minimize the number of requests and the amount of data transmitted between clients and servers, while also improving readability and discoverability.

Using application/vnd.api+json signals to both client and server that the JSON payload adheres to the JSON:API structure, which includes specific conventions for resource objects, relationships, and metadata. This allows for standardized parsing and processing, often enabling generic client libraries to interact with any JSON:API compliant endpoint.

GET /api/articles/1 HTTP/1.1
Host: example.com
Accept: application/vnd.api+json

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API Basics"
    }
  }
}

Example HTTP GET response adhering to JSON:API specification.

When to Use Which Content Type

The choice between application/json and more specific types like application/vnd.api+json depends on your API's design and requirements. Here's a decision flow to guide you:

flowchart TD
    A[Start]
    A --> B{Is your API following a specific JSON standard (e.g., JSON:API)?}
    B -->|Yes| C[Use `application/vnd.api+json` (or similar specific type)]
    B -->|No| D{Is your JSON payload a generic data structure without special conventions?}
    D -->|Yes| E[Use `application/json`]
    D -->|No| F[Consider defining a custom vendor-specific type (e.g., `application/vnd.mycompany.data+json`)]
    C --> G[End]
    E --> G[End]
    F --> G[End]

Decision flow for choosing the appropriate JSON Content-Type.

Handling Accept Headers

Just as you specify the Content-Type for what you are sending, clients should specify what they are willing to Accept in a response. The Accept header allows clients to indicate their preferred media types. Servers can then use this information to respond with the most appropriate representation of the resource.

GET /api/products HTTP/1.1
Host: example.com
Accept: application/vnd.api+json, application/json;q=0.9, */*;q=0.8

Example Accept header indicating preference for JSON:API, then generic JSON.

In this example, the client prefers application/vnd.api+json. If the server can provide that, it should. Otherwise, it will fall back to application/json (with a quality factor q=0.9 indicating a slightly lower preference), and finally to any type (*/*) as a last resort.