Page History

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.

...

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. Example should be added for success scenario 204 Created. 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.

...

schemas:
  AnchorDetails:
    type: object
    title: Anchor details by anchor Name
    properties:
      name:
        type: string
        example: Anchormy_1anchor
      dataspaceName:
        type: string
        example: Dataspacemy_1dataspace
      schemaSetName:
        type: string
        example: Schemamy_schema_set_1

ArrayOfAnchors:
  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	$ref: 'components.yml#/components/schemas/AnchorDetails'

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

'/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 change changes in the object returned for these API implementation methods in the Controller class.

...

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.

• Schema Set : https://github.com/onap/cps/blob/master/cps-service/src/test/resources/bookstore.yang
• Data : https://github.com/onap/cps/blob/master/cps-service/src/test/resources/bookstore.json

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.

...