Best Practices For APIs: Planning (1)
About The Best Practices For APIs Documents
This document is the first in a series of four briefing documents which provide advice on the planning processes for the creation of APIs.
The Importance of Planning
As with other activities, design of APIs projects requires effective planning. Rather than just adding an API to an existing service/software and moving straight into coding developers should consider planning, resourcing and managing the creation, release and use of APIs. They need to check that there isn't already a similar API available before gathering data or developing something new. Then spend time defining requirements and making sure they consider the functionality they want the user to access.
Although formal planning may not always be appropriate in some 'quick and dirty' projects some form of prototyping can be very helpful. Some areas that might need consideration are scale, weighing up efficiency and granularity.
Authors who change their specification or don't produce an accurate specification in the first place may find themselves in trouble later on in a project.
Gathering Requirements
Talking to your users and asking what they would like is just as important in API creation as user interface creation. At times it may be necessary to second-guess requirements but if you have the time it is always more efficient to engage with potential users. Technical people need to ask the user what they are actually after. You could survey a group of developers or ask members of your team.
"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."
Make The APIs Useful
When creating an API look at it both from your own perspective and from a user's perspective, offer something that can add value or be used in many different ways. One option is to consider developing a more generic application from the start as it will open up the possibilities for future work. Anticipate common requests and optimise your API accordingly. Open up the functions you're building.
Get feedback from others on how useful it is. Consider different requirements of immediate users and circumstances against archival and preservation requirements.
Collaborating on any bridges and components is a good way to help developers tap into other team knowledge and feedback.
Keep It Simple
The adage "complex things tend to break and simple things tend to work" has been fairly readily applied to the creation of Web APIs. Although simplicity is not always the appropriate remedy, for most applications it is the preferred approach. APIs should be about the exposed data rather than application design.
Keep the specifications simple, especially when you are starting out. Documenting what you plan to do will also help you avoid scope creep. Avoid having too many fields and too many method calls. Offer simplicity, or options with simple or complex levels.
Developers should consider only adding API features if there is a provable extension use case. One approach might be to always ask "do we actually need to expose this via our API?".
Make It Modular
It is better to create an API that has one function and does it well rather than an API that does many things. Good programming is inherently modular. This allows for easier reuse and sustains a better infrastructure.
The service should define itself and all methods available. This means as you add new features to the API, client libraries can automatically provide interfaces to those methods without needing new code.
As one developer commented:
"It is not enough to put a thin layer on top of a database and provide a way to get data from each table separately. Many common pieces of information can only be retrieved in a useful way by relating data between tables. A decent API would seek to make retrieving commonly-related sets of data easy."
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/>.
