This article is a draft docuemnt outlining the typical rules that should be adhered to as part of an API governance regime.
Goals
The goals of this documents are to make clear the rules, and procedures that will be adopted by us, the API vendor, in terms of updating, deprecating, and removing of API calls. The rules around communicating with end users to inform them of changes, or new releases. and the timelines around this.
These guidelines are to ensure a mutual understanding between vendor and client, and to ensure that both actors work in the best interests of all users of the system.
Versioning
The goal is to try and minimize changes where possible.
The tools will be split into two main entities.
1/ Client
The client libraries will be autogenerated from the server build.
This ensures that all client libraries will be compatible with the server code from where they were generated. As a general rule, client versions will follow semver versioning. Client releaes will be less frequent than server rleeases, as they will only need to be updated once API changes are made.
1/ Server. This will have a higher cadence of change that the client as internal functionality may change without effecting the Api contract. As such it will follow semver versioning where intenal changes will be labeled with patch version increases. A minor version change willb e a change involving extra parameters that is not considered a breaking change, and finally breaking changes will be represented by a major version change
Client libraries
Client libraries will be publised in Artifactory.
They are available here:
Documentation on the versions will be published here:
By default we will gnerate Java clients, however clients for may different versions are possible using the openapi-gnerator tool, so teams may generate their own versions of the documentation by running the tool, and pointing it to the latest Api definition, as documentated.
API docs
The API documentation will be published via swagger-UI and is available from here: URL
Change Process
In general we will try to follow the following change process, However there maybe occasions (e.g. regulatory changes etc) which may force us to deviate from this process
Once a new version of any API call is rolled out, it will come with a new version of the client
All exisitng users of the API will get an email (sent to the administrators of the Project), informing them of this new release.
The old API will be marked as deprecated in the new client but will continue to be available for a period of 1 year.
After this period the old code will be removed from the server, and old clients may fail.
After 6 months we will begin warning teams who are still using the old API of this upcoming change.
