Good APIs Project

Choose the APIs you use carefully. You can find potential APIs by signing up to RSS feeds, registering for email notifications for when new APIs are released, checking forums and searching API directories.

A decision on using an API can be made for a number of reasons (it’s the only one available, we’ve been told to use it etc.) but developers should consider checking the following:

• That it is the best fit for your needs. There may well be other APIs out there that are more appropriate. Good research is very important as it is more than likely that for popular APIs someone has probably done the hard work and produced a library for your language of choice. That said it is possible that you might have to compromise.
• What the API does. Spend some time finding out.
• How good the documentation is. Check that the documentation correctly matches the API being used. Request sample application code that communicates with the API. Initially commercial software vendors were reluctant to provide good well documented services often only provided simple data transaction services. Good documentation is now accepted as critical.
• That the APIs is connected to a functional description, i.e. an overall description of the function of the entire application.
• That there is a dialogue with the developers such as a forum or email list. This will help establish if there is continued support for bug fixes etc.
• That this API does not clash with each others you are using and will be able to ‘keep in step’.
• That it is a stable API. APIs that are still evolving are liable to change.
• How reliable it is. Some API providers have a better reputation than others.
• How popular it is. Popular APIs tend to have an active user community.
• If it is still managed. APIs which are not currently managed are unlikely to be supported.
• If selecting a product with APIs offered as part of the package ensure you evaluate the APIs too.
• What has it been coded in.
• A roadmap explaining the likely direction of future developments, if any.

Study various information sources for each potential API. These could include tutorials, online forums, mailing lists and online magazine articles offering an overview or introduction to the technology as well as the official sources of information. There are also a number of user satisfaction services available such as getsatisfaction or uservoice. The JDocs Web site maintains a searchable collection of Java related APIs and allows use comments to be added to the documentation. You may find that others have encountered problems with a particular API.

Once you have chosen an API it may be appropriate to write a few basic test cases before you begin integration.

If you’re not paying for an API then make sure that the API is part of the providers core services which they use themselves. If the provider produces a custom service just for you then if they’re not being paid then they have no incentive to keep that API up to date.

“When using APIs from others, do a risk assessment. Think about what you want for the future of the application (or part thereof) that will depend on the API, assess its value and the cost of losing it unexpectedly during its intended lifespan, guesstimate how likely it will be that the API will change significantly or become unavailable/useless in that time span. Think about an exit strategy. Consider intermediary libraries if they exist (e.g. for mapping) to allow a ready switch from one API to an equivalent. Build flexibly if it’s worth the extra effort.“