Visulima – Describing Responses

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:

/**
 * GET /ping
 * @response 200 - OK
 * @responseContent {string} 200.text/plain
 */

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 @responseContent.

/**
 * GET /users
 * @summary Get all users
 * @response 200 - A list of users
 * @responseContent {ArrayOfUsers} 200.application/json
 * @responseContent {ArrayOfUsers} 200.application/json
 * @responseContent {string} 200.text/plain
 */
// This operation returns image
/**
 * GET /logo
 * @summary Get the logo image
 * @response 200 - Logo image in PNG format
 * @responseContent {binary} 200.image/png
 */

HTTP status codes

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 (opens in a new tab)) can be used for rich text representation.

/**
 * @response 200 - OK
 * @response 400 - Bad request. User ID must be an integer and larger than 0.
 * @response 401 - Authorization information is missing or invalid.
 * @response 404 - A user with the specified ID was not found.
 * @response 5XX - Unexpected error.
 */

An API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance. However, it’s 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

A response body 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)

Objects can be defined in components:

components:
    schemas:
        User:
            type: object
            properties:
                id:
                    type: integer
                    description: The user ID.
                username:
                    type: string
                    description: The user name.

And be used with:

/**
 * @response 200 - A User object
 * @responseContent {User} 200.application/json
 */

Response that returns a file

An API operation can return a file, such as an image or PDF. If the response returns the file alone, you would typically use the binary type and specify the appropriate media type for the response content:

/**
 * GET /report
 * @summary Returns the report in the PDF format
 * @response 200 - A PDF file
 * @responseContent {binary} 200.application/pdf
 */

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

/**
 * GET /users/me
 * @summary Returns user information
 * @response 200 - A JSON object containing user name and avatar
 * @responseContent {User} 200.application/json
 */

components:
    schemas:
        User:
            type: object
            properties:
                username:
                    type: string
                avatar: # <-- image embedded into JSON
                    type: string
                    format: byte
                    description: Base64-encoded contents of the avatar image

Empty response body

Responses, such as 204 No Content, have no body. To indicate the response body is empty, do not specify @responseContent:

/**
 * @response 204 - 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:

HTTP 1/1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 2016-10-12T11:00:00Z
{ ... }

You can define custom headers for each response as follows:

/**
 * GET /ping
 * @summary Checks if the server is alive.
 * @response 200 - OK
 * @responseHeader {integer} 200.X-RateLimit-Limit - Request limit per hour.
 * @responseHeader {integer} 200.X-RateLimit-Remaining - The number of requests left for the time window.
 * @responseHeader {date-time} 200.X-RateLimit-Reset - The UTC date/time at which the current rate limit window resets.
 */

, 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.

Response examples

Examples can be defined in components:

components:
    examples:
        Jessica:
            value:
                id: 10
                name: Jessica Smith
        Ron:
            value:
                id: 11
                name: Ron Stewart

And be used as:

/**
 * POST /users
 * @summary Adds a new user
 * @response 200 - OK
 * @responseContent {User} 200.application/json
 * @responseExample {Jessica} 200.application/json.Jessica
 * @responseExample {Ron} 200.application/json.Ron
 */

Default response

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

/**
 * @response 200 - Success
 * @responseContent {User} 200.application/json
 *
 * @response 400 - Bad request
 * @responseContent {Error} 400.application/json
 *
 * @response 404 - Not found
 * @responseContent {Error} 404.application/json
 */

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.

/**
 * @response 200 - Success
 * @responseContent {User} 200.application/json
 *
 * @response default - Unexpected error
 * @responseContent {Error} default.application/json
 */

Reusing responses

Responses can be defined in components to be reused elsewhere. The following response definition:

components:
    responses:
        NotFound:
            description: The specified resource was not found
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/Error"
        Unauthorized:
            description: Unauthorized
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/Error"
    schemas:
        # Schema for error response body
        Error:
            type: object
            properties:
                code:
                    type: string
                message:
                    type: string
            required:
                - code
                - message

Can be reused as:

/**
 * GET /users
 * @summary Gets a list of users.
 *
 * @response 200 - OK
 * @responseContent {ArrayOfUsers} 200.application/json
 *
 * @responseComponent {Unauthorized} 401
 */
/**
 * GET /users/{id}
 * @summary Gets a user by ID.
 *
 * @response 200 - OK
 * @responseContent {User} 200.application/json
 *
 * @responseComponent {Unauthorized} 401
 *
 * @responseComponent {NotFound} 404
 */