Versioning Service Layer REST APIs

OIPA's REST API enables users to perform Create, Read, Update, Delete and Search operations on the OIPA Entities through Service Layer. With this enhancement OIPA's REST APIs will be given versioning capabilities so that REST APIs can be delivered independent of OIPA releases. Versioning REST APIs will help track and manage changes made to the APIs. Different versions of REST APIs should be mapped with compatible versions of OIPA. Versioning is applicable to existing REST APIs and any new REST APIs introduced in the future. A version number is added to the URI with this release and that breaks compatibility.

Prior REST API format:

Ex: http://server:port/PASService/rest/services/cases

Current REST URI format with version:

Ex: http://server:port/PASService/rest/services/v1/cases

REST Service Template / Format with version:

Ex: http://server:port/PASService/rest/services/{api_version}/{resource}

REST API Versioning

  • The APIs version designation will be a version number prefixed with a lower case 'v'.

  • The version will be 'incremented by one whenever there is a major release or a breaking change.

  • The initial release version of REST APIs will start with 'v1'.

  • On a minor release only URI that has a breaking change will have version change.

  • All the REST Services will carry the same version on URI whenever there is a major release.

If a new REST Service (PUT, POST, GET, or DELETE) which is unavailable in the previous versions of REST APIs is added, it will carry the current major release version number.

REST API documentation will provide information of the REST API version's and their compatible OIPA version's.

Required Manual Updates

Customers must add the appropriate version in the REST URI as shown in the example.