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

Compare with Current View Page History

« Previous Version 5 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 body would be different for different APIs while returning status code 200, this should be defined along with the API and should not be global.  We could define the response body schema under the schema' section in global properties.

schemas:
  AnchorDetails:
    type: object
    title: Anchor details by anchor Name
    properties:
      name:
        type: string
        example: Anchor_1
      dataspaceName:
        type: string
        example: Dataspace_1
      schemaSetName:
        type: string
        example: Schema_set_1
ArrayOfAnchors:
  type: object
  title: Anchor for schema set
  properties:
    records:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
            example: 'my_anchor'
          dataspace:
            type: string
            example: 'my_dataspace'
          schemaSet:
            type: string
            example: 'my-schema-set'
  • No labels