Best Practices For APIs: Planning (2)
Seek To Follow Standards
It is advisable to follow standards where applicable. If possible it makes sense to piggy-back on to accepted Web-oriented standards and use well know standards from international authorities: IEEE, W3C, OAI or from successful, established companies. You could refer to the W3C Web Applications Working Group. Where an existing standard isn't available or appropriate then be consistent, clear, and well-documented.
Although standards are useful and important you should be aware that some standards may be difficult to interpret or not openly available. Understanding the context within which one is operating, the contexts for which particular standards were designed and/or are applicable/appropriate and on that basis making informed decisions about the deployment of those standards.
Use Consistent Naming Structures
Use consistent, self explanatory method names and parameter structures, explicit name for functions and follow naming conventions. For example, similar methods should have arguments in the same order. Developers who fail to use naming conventions may find that their code is difficult to understand, other developers find it difficult to integrate and so go elsewhere. Naming decisions are important and there can be multilingual and cultural issues with understanding names and functionality so check your ideas with other developers.
Make The API Easier To Access
External developers are important, they can potentially add value to your service so you need to make it easy for them to do so and make sure that there is a low barrier to access. The maximum entry requirements should be a login (username and password) which then emails out a link.
If it is for a specific institution and contains what could be confidential information then it will need to contain some form of authentication that can be transmitted in the request.
If you need to use a Web API key make it straightforward to use. You should avoid the bottle neck of user authorisation, an overly complex or non-standard authentication process. One option is publish a key that anyone can use to make test API calls so that people can get started straight away. Another is to provide a copy of the service for developers to use that is separate from your production service. You could provide a developer account, developers will need to test your API so try to be amenable. If you release an open API then it needs to be open.
If possible seek to support Linked Data. Also publish resources that reflect a well-conceived domain model and use URIs that reflect the domain model.
Let Developers Know the API Exists
Making sure that potential users know about your API is vital:
- Contact your development community using email, RSS, Twitter and any other communication mechanisms you have available.
- Write about your API on developer forums. Make sure that you follow this up by having some of your developers monitoring the forum and answering questions.
- If appropriate publish API on Programmable Web.
- Blog about your API.
- Make yourself known. Twitter and chat about APIs with other developers you'll get a name as a developer and people will be interested when you release APIs.
- Add a "developers" link in the footer of your Web site. If you have released a number of APIs then the developer section of your site a comprehensive microsite with useful documentation.
- Link to working third-party applications that use your API, or third-party libraries that access it.
Version Control
Deal with versioning from the start. Ensure that you add a version number to all releases and keep developers informed. Either commit to keeping APIs the same or embed in version numbers so that applications can continue to use earlier versions of APIs if they change. You could use SourceForge or a version repository to assist.
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/>.
