By Michael Bastos, Engineering API Team Lead at Oddball
Managing APIs may seem easy at first, but like any other online product, it eventually hits scope creep and becomes something that needs to be replaced down the road. As you create new APIs to replace the old ones, you start to realize that you never thought about how to sunset or deprecate your old APIs in order to ensure that your new endpoints take center stage. Here are some considerations for those who manage API lifecycles to help make life a little easier.
I want to start off with saying that you should avoid building APIs of just one consumer or client in mind, this is tempting for both small startups or big companies combined, we sometimes tie an API to a customer for budgetary reasons but we can make the mistake of making it the norm that we don’t take scaling and or know how other customers will be implementing our API into consideration. This also makes deprecation extremely difficult because if you want to add a feature and the one customer refuses to upgrade then you’re between a rock and a hard place and find yourself moving forward while always having to support that one implementation in the corner constantly doing their own thing.
To Remove or Replace?
Given the nature and purpose of an API, replacing or removing an API from circulation requires forethought and consideration. Unlike Websites or Applications which can be updated or upgraded on a moment’s notice and which allow for near-instant change implementation, changes to APIs can have dramatic downstream impacts which may render consuming applications useless. This leaves consumers and implementers of APIs to deal with the costs of development.
We’ve all been there right? We join a team, create an amazing API that we then expose to the outside world, and it gets massive adoption across multiple companies and external partners. Upon its initial success we get asked for new features or data points to be added, we toss and turn with our teams about the best way to add those features, and we ultimately negotiate on either adding an additional endpoint which gives us the additional items we need or we give the API a new version number and let everyone know that they need to move to in order to upgrade to said feature.
In my opinion, there is no wrong way to create or deprecate an API; it’s really going to depend on your consumer’s needs and/or risk tolerances. If they believe the API is dependable enough to get behind, they will move heaven and earth to adopt it and ensure it gets further traction and publicity. If the public perceives the API as flaky (or worse: unstable) then they will only adopt what they absolutely need or find a work around that doesn’t require you or your data.
You need to take deprecation into consideration both at the start of your program and at the design of your endpoints, not at the end when you actually need to do it. Your consumers need to know that you’ve given the thought of sunsetting well in advance and have already outlined how you will do it for them so that it’s part of their adoption decision. This ensures stability and lets them know that you won’t simply pull the rug from under them when they most need it.
Deprecation it is!
The first thing you want to do is consider how you will warn them that a deprecation is coming. A lot of folks just like to publish blog posts about it and simply warn their customers. As I previously mentioned there is no wrong way to notify users, yet one of my preferred methods comes down to allowing your consumers to get more than a warning in a blog post. Instead, incorporate warnings into your API responses as well. Some of the best APIs do this by adding both a DEPRECATION header that provides a defined time frame or API version number for when the shut off will happen but also gives a DEPRECATION link or some kind of warning that it’s coming and why.
Think of it as a website notification: you would tell your customers on a website that you are going to change something or remove a feature they really like by posting a banner at the top of the page, so why wouldn’t you notify them in much the same way in your API response headers? I mention headers because at the end of the day most application builders treat the body of a response payload as gospel and treating the headers as an “anything goes” area used to share information. They need this DEPRECATION header documented boldly and proudly so that they can code for it from the very beginning and become notified on their platform whether through an event trigger or just a log trigger that this has occurred.
You should encourage them to automate this alerting process on their end for all the APIs they use from your system so that no matter the approach, no matter the usage, it’s an expected quantity. This will ultimately pay off dividends in terms of adoption when they realize that you have these sorts of standards and can be trusted to create more standards in a similar vein. I’m all for rapid development, all for getting stuff out into the world as quickly as possible, but I’m also a stickler for attention to detail when doing so, and this is one of those details that no API provider should ever miss.
Also, your documentation should make version delineation very clear and concise. I’ve used dropdowns and bulleted links in the past, always highlighting the latest current version from past versions. Keeping your deprecation notifications with your documentation is also important so that when people see that something is going to be deprecated in your docs they see it right away. I also recommend including future or Alpha/Beta versions readily available, even before you put it into production. This ensures people visiting your documentation regularly see that something is being worked on well ahead of time and will prepare themselves mentally, and maybe even financially, for the update.
Consistently Consistent
Finally, once you’ve done all the warning you can, told your consumers to automate their notifications to your API changes, and documented thoroughly not just your process but also how they will lose access to said API, you must remember to be consistent. Nothing creates more complication and drama in a program than if you say you’re going to do something and then don’t follow through. Remember, when you fail to plan for deprecating your API, you ultimately plan to fail.
Michael is a former U.S. Marine and startup CTO, working as an VA API Engineering Lead responsible for ensuring that the Benefits Team helps accomplish the mission of the VA.