Best Practices For APIs: Planning (4)
Make Sure the API Works
Make your API scalable (i.e. able to cope with a high number of hits), extendable and design for updates. Test your APIs as thoroughly as you would test your user interfaces and where relevant, ensure that it returns valid XML (i.e. no missing or invalid namespaces, or invalid characters).
Embed your API in a community and use them to test it. Use your own API in order to experience how user friendly it is.
As one developer commented:
"Once you have a simple API, use it. Try it on for size and see what works and what doesn't. Add the bits you need, remove the bits you don't, change the bits that almost work. Keep iterating till you hit the sweet spot."
Obtain Feedback On Your API
Include good error logging, so that when errors happen, the calls are all logged and you will be able to diagnose what went wrong:
"Fix your bugs in public"
If possible, get other development teams/projects using your API early to get wider feedback than just the local development team. Engage with your API users and encourage community feedback.
Provide a clear and robust contact mechanism for queries regarding the API. Ideally this should be the name of an individual who could potentially leave the organisation.
Provide a way for users of the API to sign up to a mailing list to receive prior notice of any changes.
As one developer commented:
"An API will need to evolve over time in response to the needs of the people attempting to use it, especially if the primary users of the API were not well defined to begin with."
Error Handling
Once an API has been released it should be kept static and not be changed. If you do have to change an API maintain backwards compatibility. Contact the API users and warn then well in advance and ask them to get back to you if changes affect the services they are offering. Provide a transitional frame-time with deprecated APIs support. As one developer commented:
"The development of a good set of APIs is very much a chicken-and-egg situation - without a good body of users, it is very hard to guess at the perfect APIs for them, and without a good set of APIs, you cannot gather a set of users. The only way out is to understand that the API development cannot be milestoned and laid-out in a precise manner; the development must be powered by an agile fast iterative method and test/response basis. You will have to bribe a small set of users to start with, generally bribe them with the potential access to a body of information they could not get hold of before. Don't fall into the trap of considering these early adopters as the core audience; they are just there to bootstrap and if you listen too much to them, the only audience your API will become suitable for is that small bootstrap group."
Logging the detail of API usage can help identify the most common types of request, which can help direct optimisation strategies. When using external APIs it is best to design defensively: e.g. to cater for situations when the remote services are unavailable or the API fails.
Consider having a business model in place so that your API remains sustainable. As one developer commented:
"Understand the responsibility to users which comes with creating and promoting APIs: they should be stable, reliable, sustainable, responsive, capable of scaling, well-suited to the needs of the customer, well-documented, standards-based and backwards compatible."
Acknowledgments
This document is based on advice provided by UKOLN's Good APIs project. Further information is available at <http://blogs.ukoln.ac.uk/good-apis-jisc/>.
About The Best Practices For APIs Documents
The Best Practices For APIs series of briefing documents have been published for the cultural heritage sector.
The advice provided in the documents is based on resources gathered by UKOLN for the JISC-funded Good APIs project.
Further information on the Good APIs project is available from the project's blog at <http://blogs.ukoln.ac.uk/good-apis-jisc/>.
