CPS-1197: Spike Investigate Implementation of API Versioning

URI

POST:

http://localhost:8883/cps/api/v1/dataspaces?dataspace-name=testDataspace

POST:

http://localhost:8883/cps/api/v2/dataspaces?dataspace-name=testDataspace

Response 

HTTP Code : 201

content-type: plain/text

response body : testDataspace

HTTP Code : 201

response body : NO CONTENT 

1.

change cps-rest/docs/openapi.yaml file 

  /{apiVersion}/dataspaces:
    $ref: 'cpsAdmin.yml#/dataspaces'

  /v2/dataspaces:
    $ref: 'cpsAdminV2.yml#/dataspaces'

Note : Since same URL support more then one actions (CRUD) and we need to change any one of the action, we need to create two different URL in yml file. if all the CRUD operations to be supported in v2, we can make changes in yml file as below :

 /{apiVersion}/dataspaces/{dataspace-name}/anchors/{anchor-name}/node:
    $ref: 'cpsData.yml#/nodeByDataspaceAndAnchor'

2. 

create cpsAdminV2.yml file and add POST APIs(as below) which need to be changed for v2 . 

dataspaces:
  post:
    description: Create a new dataspace
    tags:
      - cps-admin
    summary: Create a dataspace
    operationId: createDataspaceV2
    parameters:
      - $ref: 'components.yml#/components/parameters/dataspaceNameInQuery'
    responses:
      '201':
        $ref: 'components.yml#/components/responses/CreatedV2'
      '400':
        $ref: 'components.yml#/components/responses/BadRequest'
      '401':
        $ref: 'components.yml#/components/responses/Unauthorized'
      '403':
        $ref: 'components.yml#/components/responses/Forbidden'
      '409':

changes in cpsAdmin.yml for deprecated version(s):

  /{version}/dataspaces:
    post:
      deprecated: false
      tags:
      - cps-admin
      summary: Create a dataspace
      description: Create a new dataspace
      operationId: createDataspace
      parameters:
      - name: version
        in: path
        description: version 
        required: true
        schema:
          type: string
          enum: [v1]

changes in cpsAdmin.yml for APIs to be supported in all the versions as it is:

<sup>delete:
description: Delete a dataspace
tags:
- cps-admin
summary: Delete a dataspace
operationId: deleteDataspace
parameters:
- $ref: 'components.yml#/components/parameters/apiVersionInPath'
- $ref: 'components.yml#/components/parameters/dataspaceNameInQuery'</sup>

3.

add componentsV2.yml file and add below lines:

    CreatedV2:
      description: Created withoud response body

changes in components.yml to add apiVersion path parameter 

^{parameters:
apiVersionInPath:
name: apiVersion
in: path
description: apiVersion
required: true
schema:
type: string
enum: [v1, v2]}

4. 

autogenerated code in CpsAdminApi.java

   @RequestMapping(value = "/v2/dataspaces",
        produces = { "application/json" },
        method = RequestMethod.POST)
    ResponseEntity<Void> createDataspaceV2(@NotNull @Parameter(in = ParameterIn.QUERY, description = "dataspace-name" ,required=true,schema=@Schema()) @Valid @RequestParam(value = "dataspace-name", required = true) String dataspaceName);

existing APIs will also change in CpsAdminApi. now all API method will have a path parameter argument as below :

^{ResponseEntity<Void> deleteDataspace(@Parameter(in = ParameterIn.PATH, description = "apiVersion", required=true, schema=@Schema(allowableValues={ "v1", "v2" }
)) @PathVariable("apiVersion") String apiVersion, @NotNull @Parameter(in = ParameterIn.QUERY, description = "dataspace-name" ,required=true,schema=@Schema()) @Valid @RequestParam(value = "dataspace-name", required = true) String dataspaceName);}

5. 

Implement autogenerated method "createDataspaceV2" in AdminRestController.java

    @Override
    public ResponseEntity<Void> createDataspaceV2(@NotNull @Valid final String dataspaceName) {
        cpsAdminService.createDataspace(dataspaceName);
        return new ResponseEntity<>(HttpStatus.CREATED);
    }