Becoming a mature API provider is not trivial.
Here's an outline of the steps, with focus on change management.
1. Define an OpenAPI spec
Step one of your journey towards becoming a mature API provider is having an API spec.
You can be API-first which means generating code from specs, or do it the other way round.
Each of these approaches has pros and cons which we will discuss separately.
2. Check for breaking changes in the CI pipeline
Once you have an API spec you can use various tools to automate different aspects of the API lifecycle.
One of these tools is oasdiff which allows you to check for breaking changes.
Ideally, you should run oasdiff in the CI pipeline to enable a fully automated process which stops the build whenever a breaking change is detected.
3. Increment major version to indicate breaking changes
When breaking changes are detected there are several options to handle them:
Disallow the change and ask the developer to revert it
Defer the change to a future API version, for example v2. This may require a project manager approval for changing to the roadmap.
Allow the breaking change as an exception (see below).
There are two versioning conventions:
Semver: v1.0, v2.0...
Date based: Jan2024, 24-1 etc.
4. Announce breaking changes in advance, and give clients information and time to adapt
When you release a new API version you should keep the older version(s) alive for a while, this gives clients time to adapt.
Use the `Deprecated` OpenAPI keyword to mark older versions of the endpoints that are going to be removed and announce their sunset date with the `x-sunset` extension which is supported by oasdiff.
Removing endpoints without `Deprecated` and `x-sunset` keywords is considered a breaking change.
When releasing a new API version you should also publish a comprehensive changelog highlighting breaking changes alongside the new version to help clients plan and implement the migration.
5. Guarantee API lifetime
Tell your clients how long they can expect API versions to be supported, for example, one year from release, or three major versions forward.
Oasdiff requires a minimal grace period before an endpoint can be removed.
6. Define maturity levels
While breaking APIs should be minimized you still need the liberty to evolve your APIs for the benefit of your business.
To achieve this, you can mark endpoints with an `x-stability-level` extension and one of: draft, alpha, beta and stable.
Each maturity level can have a different grace period, for example, draft and alpha endpoints may be removed without notice, beta and stable endpoints may be removed after a certain grace period.
You can customize the grace periods by specifying the `--deprecation-days-beta` and `--deprecation-days-stable` flags when running oasdiff.
7. Allow exceptions
Sometimes you need to allow breaking changes, for example, for security reasons.
You should define a process to get relevant approvals for such exceptions.
Oasdiff supports exceptions with the `--warn-ignore` and `--err-ignore` flags.
8. Publish your API lifecycle policy
Once your API change process is in place, document it and publish it so your clients know what to expect.
Remember: changing APIs is okay, just don't surprise your clients and they will be happy.