Versioning of Frends APIs is different from the versioning of Processes and Subprocesses due to the fact that APIs rely on OpenAPI Specification (OAS) and usually are versioned using the URI. Also, every API method has their own Linked Process providing needed functionality, and all the Processes may not need version increments whenever the OAS changes. This relation of Processes and their OpenAPI Specification should be kept in mind to ensure compatibility and continuance of versions throughout API solutions.

Frends APIs should be versioned in the OAS and with the URI, also known as route versioning. The best practice for OAS versioning is to use the same semantic versioning that is used by Processes and Subprocesses. The URI versioning of APIs should correlate with the major version of OAS.

Below is an OAS for a User API in which the version is 1.0.1 and it correlates the URI version in the URL /api/users/v1. Whenever the major version of OAS would increment to 2.x.x, developers would need to create a copy of this API, raise the version on the server and change the URL property of the OAS to url/api/users/v2. This raise in major version requires a new instance of the OpenAPI Specification with a new version on the server URL as the API server URL cannot be altered after the initial save.

When updating the URL for a Frends API, a new specification with new Linked Processes need to be created as the URL cannot be changed after the initial save.

For the best version correlation of APIs and Processes behind its methods, it is suggested to update the Process' major version to the same as the OAS.

In the end, with APIs, the most important thing is to keep documentation up to date and use versioning as support. This creates a situation in which developers know what version to use and how compatible the changes truly are.

The next article is Best practices on Using Subprocesses