Bruno Pedro

How to stay ahead of third-party API changes

This post was originally published on the ZDNet Service Oriented blog as “How to stay ahead of third-party API changes”. 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:

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.

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.

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:

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.