API Stability and Compatibility Guarantees
In this section we will outline the way the Docugate team releases new APIs, changes existing ones and deprecates them. We are keen on offering one of the best experiences when using our APIs. Not part of this experience are things like breaking changes in publicly available interfaces. Despite these intentions, we will have to change functionality every once in a while as we keep on further development of our services. While these changes may not be avoidable, we are committed to introducing them in such a way as causes the least amount of impact on the applications that are integrated with our interfaces.
All versioning is done using the version prefix in the request path:
Get /v1/workflows/HTTP/1.1
Host: api.docugate.cloud
API Rollout process
New APIs can be introduced either as completely new functionality or as replacements for existing functionality. When releasing them, they must go through one or more prerelease stages before they are released into general availability.
The first step in the rollout will be the release of the new functionality at a new PRE API version like v2alpha1. After this, new versions can be rolled out frequently and introduce semantic changes even without incrementing the version.
Once a feature reaches maturity to be released, it will move to another PRE API version like v2beta1. From this point forward the concepts, and semantics introduced, will not change anymore.
When a feature passes muster in a beta or rc API, it will be branded a GA candidate. In this state the feature will not change anymore and the APIs specified in this version are ready to move to a major API version like v2.
When a feature is moved to GA it will be publicly announced and the API is now semantically and schematically stable.
Stability guarantees
When an application has already been integrated against certain endpoints in certain API versions, it is good to know what can happen when using those same APIs in another version. Here's what guarantees we give developers in these cases:
| Current State | Target State | Guarantees |
|---|---|---|
GA (v1) |
PRE (v2alpha1) |
No compatibility guarantees |
PRE (v2alpha1) |
PRE (v2alpha2) |
No breaking changes, semantic changes are possible |
PRE (v2alpha2) |
PRE (v2beta1) |
No compatibility guarantees |
GA (v1) |
GA (v2) |
No compatibility guarantees |
PRE (v2beta3 marked as GA candidate) |
GA (v2) |
No breaking schematic or semantic API changes |
GA (v1) |
GA (v1 updated) |
No breaking schematic or semantic API changes |
Changes caused by security vulnerabilities
If we need to introduce breaking changes that are directly or indirectly caused by a security vulnerability, they will be announced in advance through a Time To Patch Notice (TTPN) describing the change and when the patch will be rolled out. The time to patch (TTP) may vary depending on the severity of the discovered vulnerability and immediate rollouts without an advanced TTPN are possible. Rollouts due to security vulnerabilities may occur in all stages (PRE and GA) at any time after the TTP has expired.
Deprecation
Old functionality will be removed by marking a specific API as deprecated and a corresponding TTPN issued along with information on how to migrate to newer API versions. The TTP for deprecations should be as long as possible to offer developers ample time to adopt new API versions.
When a TTPN is issued for deprecated APIs, it must define a last call (LC) phase. APIs called during their LC will return status codes like 301 or 303 instead of the 2XX status code, but perform the actions requested of them as they did before entering LC. We do this in hopes of making the API consumers' code to fail without causing great harm, since the action will not actually have failed. The consumer can now choose to either adopt the new API versions or ignore the deprecation status code until the API will eventually be removed and calling them will return a 404 status code.