The following is a guest post by Bruno Pedro, editor of API UX, a collaborative blog about API User Experience and maintainer of the API Changelog, an API documentation monitor and notification service.
While most developers know that APIs change all the time, those changes aren’t communicated as often or as clearly as they should. Usually you only find out about what changed when it’s already too late -- and the only choice you have is to react by adapting your integration with the API that changed.
There are three common challenges developers face whenever an API changes:
API version change: Usually changing an API version means changing the way its methods are called. Most APIs expose the version number on the URLs used to call the methods. As an example, consider this twitter API method where the version number is part of the URL: https://api.twitter.com/1.1/statuses/mentions_timeline.json
If the API version changes, URLs will also change, meaning that you’ll have to update your consumer code to reflect those changes. Sometimes previous API versions will stop working completely, leaving you with a client code that is making calls to dead endpoints. The challenge here is being able to react quickly and change the URLs used by your API client code. If you’re using a third-party library, things can get more complicated because you’ll have to wait for the third party to be updated.
Loss of functionality: Some companies simply remove functionality from their APIs without giving any prior notice or, in the best case, giving very short notice to the API consumers. Because this information is usually buried in the API documentation, it becomes hard to keep track of it and to act accordingly.
Take a look at Linkedin’s company updates endpoint documentation. You won’t see any information about deprecated update types, but on June 12, 2014 that documentation page showed that three of the update types (new-hire, position-change and profile-change) had been deprecated. Just one day later, Linkedin removed information about the deprecation and any reference to those three types. This kind of information can only be obtained by monitoring all changes in documentation.
In both examples, developers may be caught unaware of changes. Here are two important approaches to staying current with API changes as they occur:
Test, test, test: A way to reactively mitigate problems that might occur with a third-party API integration is to periodically run tests against all the relevant endpoints. If an integration fails it means that your implementation might be broken and you should investigate further and implement the necessary changes.
There are tools available -- such as Runscope Radar -- that enable developers to set up a number of API tests and execute them periodically, notifying them if there’s any failure. Such tools also enable combined tests in which developers can invoke a number of chained API calls. Testing alone is good enough if you have enough resources to quickly react to changes. But if you want to be warned before changes happen you should also look at API documentation changes.
For example, both Linkedin and Uber API documentation changes -- cited above -- are being tracked by the API Changelog, a service that monitors API documentation pages and notifies you whenever there’s a change. (API Changelog is an API UX project.) The service enables developers to set up notifications for all the APIs with which they integrate, and get timely email notifications. Being informed enables developers and admins to react accordingly and, in most cases, adapt their code before the actual APIs break any functionality.
(Thumbnail photo: Joe McKendrick.)