Hidden Project Changes: Third Party APIs

This is the fourth post in a series about hidden project changes: things that affect scope but are easily overlooked. The topic for this post is third party APIs.

You often have to rely on third parties to finish a project. Having a dependency on third party code is a big commitment though, and you should consider it carefully.

If you have no choice but to use a certain API (perhaps it is a requirement by the customer or the only one available) reviewing it is especially important to provide accurate time estimates and properly analyze associated risks.

Selecting an API

Opting to form a dependency on a third party API is a big commitment. A good API increases productivity and speeds up development. A bad API, on the other hand, will potentially put you in a corner and slow development to a grinding halt.

Here's a checklist to use when reviewing a third party API:

1. Is the documentation...
   • updated?
   • comprehensive?
   • intuitive, easy to read and well structured?
   • indexed and/or searchable?
2. How is the API licensed?
3. Roadmap
   • How often are new versions released?
   • How quickly are hot fixes available?
   • How does the roadmap relate to the change log?
4. Issue management
   • Is there an accessible issue management system?
   • How many active bug reports are there?
   • How is the API provider responding?
5. Are there any existing use cases or references?
6. Contact
   • What kind of support is offered?
   • How quickly does the provider respond?

A lot of active bug reports is not necessarily a bad sign. On the contrary. The question is how bugs are processed, discussed and ultimately resolved by the API provider.

Is it possible to trust future release dates? Try to find out if previous versions have been released on time.

Testing the API

When an API has been chosen, you need to familiarize yourself with it. The best way to do this is to write a test suite that exercises the API. This serves three purposes:

• Learn how the API really works.
• Find inconsistencies and reveal erroneous assumptions.
• Make life easier when upgrading to a new version.

Having a set of unit tests can really help to spot bugs or undocumented changes introduced in new versions of the API.

Conclusion

Choose third party APIs carefully. It can be difficult to turn back from a dependency on third party code. One possibility is to create a bridge to the API. This makes it easier to exchange it for another one if need be.