How to stay ahead of third-party API changes
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.
More restrictive terms of use. If your business depends heavily on interactions with third-party APIs, you should be well informed about their terms of use, enabling you to offer the best possible experience to your users, without breaking any licenses. Usually in the beginning of an integration implementation, you will validate any relevant terms of use, probably with the help of a lawyer.
What happens if, later on, companies with APIs that you integrate with change their terms of use? You’ll probably want to do a legal re-validation to make sure that you can still conduct your business. The challenge is that, in most situations, changes to terms of use are not communicated to API consumers.
Uber API terms of use, for instance, recently added three items to their “Use Restrictions” which have to do with how a consumer service uses Uber data and lets their users access it. By looking at Uber’s documentation you won’t notice any change, but those three items were introduced on October 17, 2014.
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.
Monitor API documentation changes: API documentation pages are the best source of information about any changes that might happen in a near future. Most companies try to document new and deprecated functionality before actually making it available. Terms of use and other legal information are also usually available on most API documentation.
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.
Bruno Pedro's work is focused on platform and API design. Along with his API community contributions, he's the director of platform at Redbooth.
(Thumbnail photo: Joe McKendrick.)