You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

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. 

Reusing Responses

As multiple operations return the same response (status code and data), the responses section is defined as a global components object and then reference via $ref at the operation level. This is useful for error responses with the same status codes and response body. In CPS, even the success scenarios are included in the responses section as shown below.

responses:
  NotFound:
    description: The specified resource was not found
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorMessage'
  Unauthorized:
    description: Unauthorized
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorMessage'
  Forbidden:
    description: Forbidden
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorMessage'
  BadRequest:
    description: Bad Request
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorMessage'
  Conflict:
    description: Conflict
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorMessage'
  Ok:
    description: OK
    content:
      application/json:
        schema:
          type: object
  Created:
    description: Created
    content:
      text/plain:
        schema:
          type: string
  NoContent:
    description: No Content
    content: {}

The success responses Ok and No Content still would have the sample response irrespective of the API, hence these could still be included in the global components section. But as the response would be different for 'OK', this should be defined along with the API and should not be global.

  • No labels