The Flow API lifecycle
In the past, without explicit agreements with API consumers, we have become stuck supporting APIs and endpoints which were no longer really fit for purpose. With the Flow project, we would like to avoid this.
Within your contract, you will likely have certain clauses related to our API lifecycle. These clauses are designed to ensure that we're still able to evolve the API and improve the quality of the product over time.
The downside to this of course is that you may need to, very occasionally, make some subtle adjustments to your integrations.
The full specification of the time periods involved will be included in the API lifecycle section of your agreement with Scrive .
This article is intended to communicate some of the key concepts involved.
API version
When we talk about deprecating or retiring a feature or endpoint, what we're generally referring to is that a particular version of the API will be retired. We provide an Open API definition of our API and all of its endpoints. We will support several versions of the API in parallel.
When we retire a particular API version, it's possible that your integrations will continue to work as normal, without further action, if you don't happen to rely on a feature or endpoint that we've significantly changed. Betting on this is unwise however.
One strategy for managing deprecation maybe to automatically generate clients for the latest version, compile, and run your integration tests against our test API, and give warnings if you get errors with compilation or execution.
Lifecycle phases
The features and endpoints go through a particular set of stages in their life. This section aims to explain what those are and what to do at each stage.
Fully supported
No action required. This feature or endpoint is currently fully supported and we have no plans in the immediate future to remove or significantly alter it.
Deprecated
Action required. The feature will continue to function as it had previously, but not forever. If you want to avoid any errors or downtime for your integrations then you must make the required changes prior to full retirement. Full retirement may take longer than the time specified in your API lifecycle agreement, but never less.
On some occasions, it may be enough to simply regenerate your clients based on the new API version. On other occasions, you may need to make some subtle changes to your code itself. We will endeavour to communicate how to upgrade as painlessly as possible.
Retired
Action urgently required. If you have not updated your integration in time then you will potentially see errors from our API if your requests no longer match what we expect, or our responses are not what your system expects.
Feature track
While we are working on a particular feature or set of API endpoints, it will be usually be available sooner as part of the Experimental track. Early access comes at the cost of lower API stability.
Experimental
If you are using our experimental features and endpoints, then you should recognize that we offer lower guarantees of correctness than we would for a production track features and endpoints.
When an endpoint is deprecated, you can expect a significantly shorter time frame before full retirement than for features and endpoints that are in the production track.
In terms of time frame from deprecation to retirement, think months not years.
When we are satisfied that a particular endpoint or feature is ready for the big time, it will process to the production track.
Production
These are stable features and endpoints. As such, you can be a lot surer that we're relatively satisfied with their design, and that we're pretty confident that they work exactly as intended.
Obviously, even stable APIs need to evolve and chance sometimes. When this is the case, you will receive a much longer timeline in which to make the necessary changes that you would for experimental track features and endpoints.
In terms of time frame from deprecation to retirement, think a year or more.