[ADP-122] Accept

Overview

The Accept header in HTTP requests specifies the media types that are acceptable for the response. This guideline outlines best practices for using the Accept header in API design, with references to RFC 9110, content negotiation, HTTP problem details (RFC 9457), and OpenAPI descriptions.

Guidance

• The client SHOULD request the Accept header.

• The accepting criteria are:

  • Accept: */* means the client could accept any content type (MIME type)
  • Accept: text/* means the client could accept any subtype under text type.

• MAY support versioning-based negotiation.

• SHOULD design your API to support application/json for most responses and binary formats when necessary.

  • If no Accept header is provided by the client, default to application/json.

• SHOULD always respect the client's preferences indicated in the Accept header. If the server cannot provide a response in any of the requested formats, it should return a 406 Not Acceptable status code with an appropriate problem details response.

  HTTP/1.1 406 Not Acceptable
  Content-Type: application/problem+json
  
  {
    "type": "https://example.com/problems/not-acceptable",
    "title": "Not Acceptable",
    "status": 406,
    "detail": "The requested media type is not supported. Supported media types: application/json, application/octet-stream"
  }

• SHOULD implement content negotiation on the server side to handle application/json and binary formats based on the Accept header. This ensures that the server can respond appropriately to different client requests. See Content Negotiation.

• Clearly document the supported media types in your API documentation to help clients understand what formats they can request and how to properly use the Accept header.

• MAY leverage quality values (q-values) to prioritize media types when multiple types are acceptable. This ensures the server can return the most preferred format available.

Semantics

See Content Negotiation.

Example

Client Request with Accept Header:

GET /resources HTTP/1.1
Host: api.example.com
Accept: application/json, application/octet-stream;q=0.9

Server Response Handling:

• application/json is the most preferred media type.

• If the server supports application/json, it should respond with:

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
    "data": "sample response"
  }

• If the server only supports application/octet-stream, it should respond with:

  HTTP/1.1 200 OK
  Content-Type: application/octet-stream
  
  [binary data]

• If the requested media types are unsupported, the server should respond with:

  HTTP/1.1 406 Not Acceptable
  Content-Type: application/problem+json
  
  {
    "type": "https://example.com/problems/not-acceptable",
    "title": "Not Acceptable",
    "status": 406,
    "detail": "The requested media type is not supported. Supported media types: application/json, application/octet-stream"
  }

Example with OpenAPI

According to https://swagger.io/docs/specification/describing-parameters/, you don't need to specify Accept header in the document but the response header of Content-Type .

OpenAPI Specification Snippet:

To describe the Accept header in OpenAPI, you specify the different media types that the server can respond with for each endpoint. Here is an example:

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /resources:
    get:
      summary: Get resources
      operationId: getResources
      responses:
        '200':
          description: Successful response
          content:
            'application/json; version=public/v2':
              schema:
                type: object
            application/json:
              schema:
                type: object
            application/octet-stream:
              schema:
                type: string
                format: binary
        '406':
          description: Not Acceptable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string

This OpenAPI snippet defines the supported media types (application/json and application/octet-stream) for the GET /resources endpoint and specifies the 406 Not Acceptable response using the problem details format.

Reference

• https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept

Changelog

• 2024.09.24 Remove unwanted /api path in the samples