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:
1paths:2 /ping:3 get:4 responses:5 "200":6 description: OK7 content:8 text/plain:9 schema:10 type: string11 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.
1paths:2 /users:3 get:4 summary: Get all users5 responses:6 "200":7 description: A list of users8 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: string18
19 # This operation returns image20 /logo:21 get:22 summary: Get the logo image23 responses:24 "200":25 description: Logo image in PNG format26 content:27 image/png:28 schema:29 type: string30 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.
1responses:2 "200":3 description: OK4 "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 anarray
— 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:
1responses:2 "200":3 description: A User object4 content:5 application/json:6 schema:7 type: object8 properties:9 id:10 type: integer11 description: The user ID.12 username:13 type: string14 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.
1responses:2 "200":3 description: A User object4 content:5 application/json:6 schema:7 $ref: "#/components/schemas/User"8 components:9 schemas:10 User:11 type: object12 properties:13 id:14 type: integer15 description: The user ID.16 username:17 type: string18 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
:
1paths:2 /report:3 get:4 summary: Returns the report in the PDF format5 responses:6 "200":7 description: A PDF file8 content:9 application/pdf:10 schema:11 type: string12 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:
1paths:2 /users/me:3 get:4 summary: Returns user information5 responses:6 "200":7 description: A JSON object containing user name and avatar8 content:9 application/json:10 schema:11 type: object12 properties:13 username:14 type: string15 avatar: # <-- image embedded into JSON16 type: string17 format: byte18 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.
1responses:2 "200":3 description: A JSON object containing pet information4 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:
1responses: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:
1HTTP 1/1 200 OK2X-RateLimit-Limit: 1003X-RateLimit-Remaining: 994X-RateLimit-Reset: 2016-10-12T11:00:00Z5
6{ ... }
You can define custom headers
for each response as follows:
1paths:2 /ping:3 get:4 summary: Checks if the server is alive.5 responses:6 "200":7 description: OK8 headers:9 X-RateLimit-Limit:10 schema:11 type: integer12 description: Request limit per hour.13 X-RateLimit-Remaining:14 schema:15 type: integer16 description: The number of requests left for the time window.17 X-RateLimit-Reset:18 schema:19 type: string20 format: date-time21 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:
1responses:2 "200":3 description: Success4 content:5 application/json:6 schema:7 $ref: "#/components/schemas/User"8
9 # These two error responses have the same schema10 "400":11 description: Bad request12 content:13 application/json:14 schema:15 $ref: "#/components/schemas/Error"16 "404":17 description: Not found18 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.
1responses:2 "200":3 description: Success4 content:5 application/json:6 schema:7 $ref: "#/components/schemas/User"8
9 # Definition of all error statuses10 default:11 description: Unexpected error12 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.
1paths:2 /users:3 get:4 summary: Gets a list of users.5 response:6 "200":7 description: OK8 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: OK20 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 components30components:31 responses:32 NotFound:33 description: The specified resource was not found34 content:35 application/json:36 schema:37 $ref: "#/components/schemas/Error"38 Unauthorized:39 description: Unauthorized40 content:41 application/json:42 schema:43 $ref: "#/components/schemas/Error"44
45 schemas:46 # Schema for error response body47 Error:48 type: object49 properties:50 code:51 type: string52 message:53 type: string54 required:55 - code56 - 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:
1GET /something -> {200, schema_1}2GET /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
Did not find what you were looking for? Ask the community
Found a mistake? Let us know