What Makes a Good API then?

Thanks to everyone who has already submitted answers to the GOOD APIs survey , there is still 3 days left if you haven’t done so already.

A few top tips are already surfacing.

Make it Useful
When creating an API look at it from a user’s perspective, offer something that can add value or be used in many different ways. Get feedback from others on how useful it is.
Keep it clean and simple
Make sure it is good quality but keep it simple. APIs should be about the exposed data rather than application design. It has been argued that “Complex things tend to break and simple things tend to work.” A good API will be easy to use and hard to misuse.
Follow standards
Refer to the W3C Web Applications Working Group. Use consistent, self explanatory names and follow naming conventions.
Make it easy to access
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 you need to use a Web API key make it straightforward to use. You should avoid the bottle neck of user approval.
Provide it in different languages
A simple API is usually REST/HTTP based, with XML delivery of a simple schema e.g. RSS. This should be the minimum. You may want to offer toolkits for different languages.
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. Once an API has been released services will be using it so a modular approach will mean less complication.
Keep it abstract
By avoiding set variables and conditions it is more likely that your API will be used in many different ways.
Provide documentation
Although a good API should be intuitive and not need documentation it is good practice to provide clear useful documentation and examples for prospective developers. This will result in less time spent taking support calls. Embedding the API in a community also helps.
Make sure it works
Test it and then test it again. Make it scalable i.e. able to cope with a high number of hits, extendable and design for updates. You could add a version number and keep developers informed.
Consider a business model
A business model will mean that your API remains sustainable

If you have anymore to add then please do. Remember that this work is not restricted to the Web.

Posted in tips. Comments Off