OpenAPI work procedure

This article describes how a daily routine looks like for developer in case of OpenAPI file. OpenAPI file is simply a descriptioon of API. It describes:

  • the path and all parameters needed to call API
  • behavior of API
  • possible HTTP response codes
  • response data structures etc…

Every time you write a new API or adjust existing one you need to update OpenAPI specification. More information about OpenAPI standard you can find here. The OpenAPI specification for all APIs delivered in DC1 standard is kept in GitLab. Note, that all API specifications for standard DC1 are kept in one JSON file. The files are stored in two branches:

  • main - to keep official version of API specification
  • develop - to keep OpenAPI under development.

The folder structure in Git is as follows:

  • openapi - this folder contains all OpenAPI specifications
  • openapi/base/v1 - this folder contains base DC1 API specification delivered from PD
  • openapi/{customer}/v1 - this folder contains customer API specification. These APIs are only for Cloud-private customers.

Versioning (DC1 base)

Currently we are working on version 1 of API at Iptor. The folder structure is prepared to handle more versions but it is a business decision when we roll out version 2.

Adding new API (DC1 base)

  1. If you are about to add a new API to OpenAPI do it at the end of “paths” section of the OpenAPI file. Add tag “Under development”. Do it in your own branch based on the current version from ‘develop’ branch.
  2. When API is ready to be published internally, merge your changes to ‘develop’ branch. It will deploy OpenAPI specification on our PD internal deployment server dkdcvs134.ibs.net. At this moment you can see your API specification in internal PD API documentation server, under tag “Under development”. Now you can test your API with Postman. You can use Mock server, etc…
  3. When Your RPG program is ready and tested (promoted to production and is waiting for build), you can merge (or manually move your work) to main branch. Before merge to main branch make sure that your develop branch is up to date. If not, merge changes from main to develop first. NOTE: the API is still “under development” tag. This prevent situation that someone (customer) will see your API and wil complain why it is not working. Your API is still under developmetn until backend RPG program is installed on customer side.
  4. Increment the version of OpenAPI specification in the file by one in “minor” segment and zero the patch version.

Increment the minor version. If it is 1.2.42 …

{
   ...
   "info":{
       ...
       "version":"1.2.42"
   }
}

after change it should be 1.3.0.

{
   ...
   "info":{
       ...
       "version":"1.3.0"
   }
}

Modifing existing API (DC1 base)

It is possible to modify existing API only if you do “non breaking” changes. What is a non breaking change?

  • modified text, description, tags, summary in OpenAPI specification
  • adding new optional query parameters to API
  • adding optional elements to payload
  • adding extra data to response but not changing general structure of response (extanding response)
  • adding more descriptive error descriptions
  • changing query parameters from mandatory to optional
  • changing payload elements from required to optional

If your change fulfill above points then it is possible to modify API.

  1. If you are about to modify existing API in OpenAPI, do it in your own branch based on current version from develop branch.
  2. When API is ready to publish internally, merge your changes to “develop” branch. It will deploy OpenAPI specification on our PD internal deployment server dkdcvs134.ibs.net. At this moment you can see your API specification in internal PD API documentation server. Now you can test your API with Postman. You can use Mock server, etc…
  3. When your RPG program is ready or your OpenAPI change is ready and tested (promoted to production and is waiting for build), you can merge (or manually move your work) to main branch. Before merge to main branch make sure that your develop branch is up to date. If not, merge changes from main to develop first.
  4. Increment version of OpenAPI specification in the file by one in “minor” or patch segment. Set patch to zero if you incremented the minor.

Example1: Increment minor version. If it is 1.2.42 …

{
   ...
   "info":{
       ...
       "version":"1.2.42"
   }
}

after change it should be 1.3.0.

{
   ...
   "info":{
       ...
       "version":"1.3.0"
   }
}

Example2: Increment patch version. If it is 1.2.42 …

{
   ...
   "info":{
       ...
       "version":"1.2.42"
   }
}

after change it should be 1.2.43.

 {
    ...
    "info":{
        ...
        "version":"1.2.43"
    }
 }

Deleting API

It is not allowed to delete API. The only possibility to mark that an API will be deleted is to set it to deprecated.

  1. Go to OpenAPI spec. It is allowed to work on develop branch.
  2. Set API as deprecated=true in OpenAPi file and commit changes. It will deploy OpenAPI specification on our PD internal deployment server dkdcvs134.ibs.net. At this moment you can see your API specification in internal PD API documentation server. Now you can test your API with Postman. You can use Mock server, etc…
  3. When You are ready to publish this info, you can merge (or manually move your work) to main branch. Before merge to main branch make sure that your develop branch is up to date. If not, merge changes from main to develop first.
  4. Increment version of OpenAPI spec in file by one in “minor” segment. Set patch to zero. See examples above.

When to change tags

When you are convinced that DC1 backend build including your API is installed for customers you can change the tag from “Under development” to a proper tag. The change of tags must be synchronised with the installation of builds.

When to publish OpenAPI spec

Publishing OpenAPI spec must be synchronised with DC1 builds. Usually it is connected to changing tags from “under development” to final one. When your OpenAPI is ready to be published then go to GitLab and release new version of API. The tag may correspond to OpenAPI version in the file. Adding tag and release notes will triger build of image api-documentation and api-mock images. It will also triger deployment on OpenShift test cluseter (iptor-go project).

Working with customer APIs (Cloud-Private)

There is already a folder structure prepared for customer (cloud-private) environments. Whenever you need to add new API for customer (as part of customer modification), do it in a separate file located in correct place in the folder structure. Please, use customer name in the name of the file. See OpenAPI naming standards. Before you add first OpenAPI file make sure everything else is configured in GitLab:

  • Make sure the merge config includes your new OpenAPI file.
  • Make sure configuration of api-documentation includes new file in URLS variable

example (see the third line of url):

URLS: >
      [
        { url: "doc/base/v1/iptor-erp-api.json", name: "Iptor base ERP APIs V1"},
        { url: "doc/base/v1/iptor-crm-api.json", name: "Iptor base CRM APIs V1"},
        { url: "doc/customer-a/v1/customer-a-erp-api.json", name: "API for customer-a V1"}
      ]