Your API is a long-term promise.
I promise that my API actions, and how they behave will work as described in the documentation.
This promise is hard to uphold. Time isn’t explicitly defined in that agreement. The API creator may think they can change their API whenever it’s necessary. The API consumer probably thinks the API will remain the same forever.
These two assumptions directly oppose each other.
APIs that want to iterate and improve their product could email all of their consumers, asking them to update their integrations. But what if those companies don’t have full-time software engineers on staff? What if they have a 6-month turnaround on their engineering process? What if they don’t have anyone listening to the email address attached to their API account?
APIs that want to create a perfectly stable platform could write their API once, and never make any changes. But what if you need to deprecate a feature completely? What if your website grows and evolves, leaving your API as a confusing, inconsistent facet of your product? What if you notice a glaring oversight in your original design?
In the real world, it’s more complex. I’ve been working on a frequently changing API for many years now, and would like to share some of the techniques I’ve learned to achieve long term stability for your API.
- Understand the limitations of your API consumers.
- Design APIs with change in mind.
- Design and develop APIs with your support team in mind.
- Be creative and retain backwards compatibility.
I’m going to expand on all of these topics in future posts. Follow me, or check back later for more updates!