You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 14
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 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.
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: array
items:
type: object
properties:
name:
type: string
example: my_anchor
dataspace:
type: string
example: my_dataspace
schemaSet:
type: string
example: my-schema-set
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 in the object returned for these 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.
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.