In my previous blog post I wrote about the necessity to define the life-cycle of your API which includes a process on how to introduce possibly breaking changes to your API. The logical next step is to discuss possible solutions. Luckily, there are already some sources. I will focus on API design patterns as documented in our book “Patterns for API Design” (you can get a discount voucher here). Patterns are documented experiences from many projects. As such these are not inventions by their authors but are solutions found in the wild.
What do you want to guarantee?
Essentially, the main question is how much flexibility you want to keep as an API provider versus how much guarantees do you want to (or must) give to your API clients. This balance might also change over time. If you are releasing a new API, you can expect more changes because you learn together with your API clients what is relevant, what can be improved, and what is required. But you also learn what you don’t need and what is not (or rarely) required and what you want to phase out. As a result, you likely want to be more flexible before stabilizing your API.
Experimental Preview
One pattern that might be useful in this context is the Experimental Preview Pattern: Essentially, you offer an API by explicitly giving no guarantees. The intent is to get feedback by interested parties on whether the offered functionality matches the expectations. Things might change fast so other parties know that they need to reserve resources to keep up with changes and implementing them in their client systems.
Aggressive Obsolescence
If things are getting more stable, it is time to give more guarantees to your clients thereby encouraging them to use your API because the costs of keeping up with changes is plannable (and likely reduced). One way is to change the API and if functions or data fields need to be removed, they are marked as deprecated. The deprecation notice also includes a deadline when this feature will be decommissioned. This pattern is called Aggressive Obsolescence.
Two-In-Production
One often used option is to offer two API versions in parallel (Two-In-Production Pattern): a breaking change leads to a new API version that is either offered at a new endpoint, accessed via content-negotiation or query parameters. However, the old version is left active until a third version is released. Because only two versions may be active, the oldest version is taken off the platform.
Limited Lifetime Guarantee
Because in the Two-In-Production pattern the availability of an older API version is subject to the frequency of API version releases, it is not well plannable for API clients if there are frequent releases. In this case it might be better for API clients to receive a Limited Lifetime Guarantee: The API provider guarantees that an API is made available in an unmodified or at least backwards-compatible manner until a guaranteed deadline.
Mix and Match
Of course, these patterns can also be combined. For example, an API provider might offer a Two-In-Production pattern combined with a Limited Lifetime Guarantee. These patterns should inspire you and give you ideas. For advantages and disadvantages of these patterns and implementation hints you can have a look at the Website, in the book or learn those with the authors in a hands-on training.
We disuss these and many more patterns in our book "Patterns for API Design". You can get a discount voucher for the book here (or order it on Amazon).
|
<<< Previous Blog Post Why you will make breaking changes to your API |
Next Blog Post >>> Why is API Life-Cycle Important? |