OpenSRP API Versioning

Owned by Benjamin Mwalimu Mulyungi
Last updated: Jun 03, 2020
2 min read

Background

OpenSRP uses the REST (Representational state transfer) framework to create its API endpoints. This framework defines some standards to follow during the design of API’s

OpenSRP is committed to building endpoints that adhere to these standards. This might necessitate the building of new endpoints for already existing functionality. This then necessitates the need to version API’s endpoints for easier use.

To solve this we decided to add the version number to the endpoint URL path. OpenSRP currently has 2 versions of some of its endpoint e.g the settings endpoint. The addition of v2 on the endpoint path denotes that the endpoint is the second version

How to version endpoints

Add the version number before the endpoint noun on the path e.g https://ona-stage.smartregister.org/opensrp/rest/v2/settings. In case we already have a v2 endpoint version then the version number is incremented by 1.

When to and version number to an endpoint

We only up-version the endpoints when a breaking change is made. These include things like:

  • A change in the format of the response data for one or more calls

  • A change in the format of the request payload for the POST, PUT & PATCH HTTP methods that does not maintain backward compatibility

  • A change in the response type (i.e. changing an integer to a float)

  • Removing any part of the API.

Breaking changes should always result in a change to the major version number for an API or content response type.

Non-breaking changes, such as adding new endpoints or new response parameters, do not require a change to the major version number. However, it can be helpful to track the minor versions of APIs when changes are made to support customers who may be receiving cached versions of data or may be experiencing other API issues.

Resources