Describing Responses

An API specification needs to specify the responses for all API operations. Each operation must have at least one response defined, usually a successful response. A response is defined by its HTTP status code and the data returned in the response body and/or headers. Here is a minimal example:

1
paths:
2
  /ping:
3
    get:
4
      responses:
5
        "200":
6
          description: OK
7
          content:
8
            text/plain:
9
              schema:
10
                type: string
11
                example: pong

Response Media Types

An API can respond with various media types. JSON is the most common format for data exchange, but not the only one possible. To specify the response media types, use the content keyword at the operation level.

1
paths:
2
  /users:
3
    get:
4
      summary: Get all users
5
      responses:
6
        "200":
7
          description: A list of users
8
          content:
9
            application/json:
10
              schema:
11
                $ref: "#/components/schemas/ArrayOfUsers"
12
            application/xml:
13
              schema:
14
                $ref: "#/components/schemas/ArrayOfUsers"
15
            text/plain:
16
              schema:
17
                type: string
18

19
  # This operation returns image
20
  /logo:
21
    get:
22
      summary: Get the logo image
23
      responses:
24
        "200":
25
          description: Logo image in PNG format
26
          content:
27
            image/png:
28
              schema:
29
                type: string
30
                format: binary

More info: Media Types.

HTTP Status Codes

Under responses, each response definition starts with a status code, such as 200 or 404. An operation typically returns one successful status code and one or more error statuses. To define a range of response codes, you may use the following range definitions: 1XX, 2XX, 3XX, 4XX, and 5XX. If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. Each response status requires a description. For example, you can describe the conditions for error responses. Markdown (CommonMark) can be used for rich text representation.

1
responses:
2
  "200":
3
    description: OK
4
  "400":
5
    description: Bad request. User ID must be an integer and larger than 0.
6
  "401":
7
    description: Authorization information is missing or invalid.
8
  "404":
9
    description: A user with the specified ID was not found.
10
  "5XX":
11
    description: Unexpected error.

Note that an API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance. However, it is expected to cover successful responses and any known errors. By “known errors” we mean, for example, a 404 Not Found response for an operation that returns a resource by ID, or a 400 Bad Request response in case of invalid operation parameters.

Response Body

The schema keyword is used to describe the response body. A schema can define:

an object or an array — typically used with JSON and XML APIs,
a primitive data type such as a number or string – used for plain text responses,
a file – (see below).

Schema can be defined inline in the operation:

1
responses:
2
  "200":
3
    description: A User object
4
    content:
5
      application/json:
6
        schema:
7
          type: object
8
          properties:
9
            id:
10
              type: integer
11
              description: The user ID.
12
            username:
13
              type: string
14
              description: The user name.

or defined in the global components.schemas section and referenced via $ref. This is useful if multiple media types use the same schema.

1
responses:
2
  "200":
3
    description: A User object
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User"
8
    components:
9
      schemas:
10
        User:
11
          type: object
12
          properties:
13
            id:
14
              type: integer
15
              description: The user ID.
16
            username:
17
              type: string
18
              description: The user name.

Response That Returns a File

An API operation can return a file, such as an image or PDF. OpenAPI 3.0 defines file input/output content as type: string with format: binary or format: base64. This is in contrast with OpenAPI 2.0, which uses type: file to describe file input/output content. If the response returns the file alone, you would typically use a binary string schema and specify the appropriate media type for the response content:

1
paths:
2
  /report:
3
    get:
4
      summary: Returns the report in the PDF format
5
      responses:
6
        "200":
7
          description: A PDF file
8
          content:
9
            application/pdf:
10
              schema:
11
                type: string
12
                format: binary

Files can also be embedded into, say, JSON or XML as a base64-encoded string. In this case, you would use something like:

1
paths:
2
  /users/me:
3
    get:
4
      summary: Returns user information
5
      responses:
6
        "200":
7
          description: A JSON object containing user name and avatar
8
          content:
9
            application/json:
10
              schema:
11
                type: object
12
                properties:
13
                  username:
14
                    type: string
15
                  avatar: # <-- image embedded into JSON
16
                    type: string
17
                    format: byte
18
                    description: Base64-encoded contents of the avatar image

anyOf, oneOf

OpenAPI 3.0 also supports oneOf and anyOf, so you can specify alternate schemas for the response body.

1
responses:
2
  "200":
3
    description: A JSON object containing pet information
4
    content:
5
      application/json:
6
        schema:
7
          oneOf:
8
            - $ref: "#/components/schemas/Cat"
9
            - $ref: "#/components/schemas/Dog"
10
            - $ref: "#/components/schemas/Hamster"

Empty Response Body

Some responses, such as 204 No Content, have no body. To indicate the response body is empty, do not specify a content for the response:

1
responses:
2
  "204":
3
    description: The resource was deleted successfully.

Response Headers

Responses from an API can include custom headers to provide additional information on the result of an API call. For example, a rate-limited API may provide the rate limit status via response headers as follows:

1
HTTP 1/1 200 OK
2
X-RateLimit-Limit: 100
3
X-RateLimit-Remaining: 99
4
X-RateLimit-Reset: 2016-10-12T11:00:00Z
5

6
{ ... }

You can define custom headers for each response as follows:

1
paths:
2
  /ping:
3
    get:
4
      summary: Checks if the server is alive.
5
      responses:
6
        "200":
7
          description: OK
8
          headers:
9
            X-RateLimit-Limit:
10
              schema:
11
                type: integer
12
              description: Request limit per hour.
13
            X-RateLimit-Remaining:
14
              schema:
15
                type: integer
16
              description: The number of requests left for the time window.
17
            X-RateLimit-Reset:
18
              schema:
19
                type: string
20
                format: date-time
21
              description: The UTC date/time at which the current rate limit window resets.

Note that, currently, OpenAPI Specification does not permit to define common response headers for different response codes or different API operations. You need to define the headers for each response individually.

Default Response

Sometimes, an operation can return multiple errors with different HTTP status codes, but all of them have the same response structure:

1
responses:
2
  "200":
3
    description: Success
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User"
8

9
  # These two error responses have the same schema
10
  "400":
11
    description: Bad request
12
    content:
13
      application/json:
14
        schema:
15
          $ref: "#/components/schemas/Error"
16
  "404":
17
    description: Not found
18
    content:
19
      application/json:
20
        schema:
21
          $ref: "#/components/schemas/Error"

You can use the default response to describe these errors collectively, not individually. “Default” means this response is used for all HTTP codes that are not covered individually for this operation.

1
responses:
2
  "200":
3
    description: Success
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User"
8

9
  # Definition of all error statuses
10
  default:
11
    description: Unexpected error
12
    content:
13
      application/json:
14
        schema:
15
          $ref: "#/components/schemas/Error"

Reusing Responses

If multiple operations return the same response (status code and data), you can define it in the responses section of the global components object and then reference that definition via $ref at the operation level. This is useful for error responses with the same status codes and response body.

1
paths:
2
  /users:
3
    get:
4
      summary: Gets a list of users.
5
      response:
6
        "200":
7
          description: OK
8
          content:
9
            application/json:
10
              schema:
11
                $ref: "#/components/schemas/ArrayOfUsers"
12
        "401":
13
          $ref: "#/components/responses/Unauthorized" # <-----
14
  /users/{id}:
15
    get:
16
      summary: Gets a user by ID.
17
      response:
18
        "200":
19
          description: OK
20
          content:
21
            application/json:
22
              schema:
23
                $ref: "#/components/schemas/User"
24
        "401":
25
          $ref: "#/components/responses/Unauthorized" # <-----
26
        "404":
27
          $ref: "#/components/responses/NotFound" # <-----
28

29
# Descriptions of common components
30
components:
31
  responses:
32
    NotFound:
33
      description: The specified resource was not found
34
      content:
35
        application/json:
36
          schema:
37
            $ref: "#/components/schemas/Error"
38
    Unauthorized:
39
      description: Unauthorized
40
      content:
41
        application/json:
42
          schema:
43
            $ref: "#/components/schemas/Error"
44

45
  schemas:
46
    # Schema for error response body
47
    Error:
48
      type: object
49
      properties:
50
        code:
51
          type: string
52
        message:
53
          type: string
54
      required:
55
        - code
56
        - message

Note that responses defined in components.responses are not automatically applied to all operations. These are just definitions that can be referenced and reused by multiple operations.

Linking Response Values to Other Operations

Certain values in the response could be used as parameters to other operations. A typical example is the “create resource” operation that returns the ID of the created resource, and this ID can be used to get that resource, update or delete it. OpenAPI 3.0 provides the links keyword to describe such relationships between a response and other API calls. For more information, see Links.

FAQ

Can I have different responses based on a request parameter? Such as:

1
GET /something -> {200, schema_1}
2
GET /something?foo=bar -> {200, schema_2}

In OpenAPI 3.0, you can use oneOf to specify alternate schemas for the response and document possible dependencies verbally in the response description. However, there is no way to link specific schemas to certain parameter combinations.

Reference

Response Object

MediaType Object

Components Object

Did not find what you were looking for? Ask the community
Found a mistake? Let us know