Versions Compared

Old Version 3

changes.mady.by.user aditya puthuparambil

Saved on

compared with

New Version 4

changes.mady.by.user aditya puthuparambil

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

Expand
titleCurrent Response component in CPS
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.