CPS-428 - Getting issue details... STATUS

Adding Responses for API operations

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 Response

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.

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 Created 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(OK), 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 components.

Anchor Schema sample 
schemas:
  AnchorDetails:
    type: object
    title: Anchor details by anchor Name
    properties:
      name:
        type: string
        example: my_anchor
      dataspaceName:
        type: string
        example: my_dataspace
      schemaSetName:
        type: string
        example: my_schema_set
Array of anchors schema 
ArrayOfAnchors:
  type: array
  items:
	$ref: 'components.yml#/components/schemas/AnchorDetails'

These schemas could be used in the API specification as below:

Get all anchors definition using response and example 
'/v1/dataspaces/{dataspace-name}/anchors':
    get:
      description: 'Read all anchors, given a dataspace'
      tags:
        - cps-admin
      summary: Get anchors
      operationId: getAnchors
      parameters:
        - name: dataspace-name
          in: path
          description: dataspace-name
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfAnchors'
	    '400':
          $ref: 'components.yml#/components/responses/BadRequest'
        '401':
          $ref: 'components.yml#/components/responses/Unauthorized'
        '403':
          $ref: 'components.yml#/components/responses/Forbidden'
        '404':
          $ref: 'components.yml#/components/responses/NotFound'

This change would also introduce changes in the API implementation methods in the Controller class.

Adding Examples

You can add examples to parameters, properties and objects to make OpenAPI specification of your web service clearer. Examples can be read by tools and libraries that process your API in some way. For example, an API mocking tool can use sample values to generate mock requests. In CPS, the examples are added at object and property level.

For schema set and data node, the bookstore model and data should be used as example.

Note: ErrorMessage is a common schema used for all error scenarios. And as the examples as defined at property level, different errors correspond to the same example.

  • No labels

4 Comments

  1. Toine Siebelink

    Anchor_1
    Cant comment inline on the examples, but I prefer what you have in your second example: 'my_anchor' over 'anchor_1' for the examples. Ie. use 'mySomething instead of 'something_1' in all examples...

    1. aditya puthuparambil

      done

  2. Toine Siebelink

    Hi aditya puthuparambil I would also like to add a note that for any model-related example in CPS-Core my proposal is to use the bookstore model and related examples. I think those are the most easy to understand examples. We can use the model that is already used in some (unit) tests

    1. aditya puthuparambil

      done