ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-126] Content-Type ​

Overview ​

In RESTful API design, the Content-Type header specifies the media type of the resource being sent to or returned by the server. It ensures that the server and the client correctly interpret the content of the message. This header is essential for both request and response messages.

Guidance ​

  • When a client sends data to the server (e.g., via POST or PUT), it MUST include the Content-Type header to indicate the type of the data being sent.
    • Common content types include application/json, application/xml, text/plain, etc.
  • The server SHOULD include the Content-Type header in the response to specify the type of data being returned.
    • This helps clients correctly process the response data.
  • Clients can use the Accept header to inform the server of the types of responses it can handle.

    • The server should honor the Accept header and return data in one of the acceptable formats or respond with a 406 Not Acceptable status code if it cannot produce any of the acceptable formats.

      http
      HTTP/1.1 406 Not Acceptable
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://example.com/problems/not-acceptable",
  "title": "Not Acceptable",
  "status": 406,
  "detail": "The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.",
  "instance": "/users"
}

Example ​

Request Example ​

A client sending a JSON payload to create a new user:

http
POST /users HTTP/1.1
Host: example.com
Content-Type: application/json
{
    "name": "John Doe",
    "email": "john.doe@example.com"
}

Response Example ​

The server responding with JSON data:

http
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": 123,
    "name": "John Doe",
    "email": "john.doe@example.com"
}

Example with OpenAPI ​

Below is an OpenAPI 3.0 example defining an API with proper Content-Type headers:

yaml
openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  email:
                    type: string
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: Not Acceptable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri
      required:
        - type
        - title
        - status
        - detail
        - instance
      example:
        type: "https://example.com/problems/not-acceptable"
        title: "Not Acceptable"
        status: 406
        detail: "The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request."
        instance: "/users"

Reference ​