Good APIs Project

Yesterday Google released their API Playground. This will be a great tool for anyone new to using Google’s APIs. It is essentially for teaching developers how to use Google’s JavaScript APIs and is currently loaded with over 170 samples for 8 Google JavaScript APIs (Maps, Search, Feeds, Calendar, Visualization, Language, Blogger, Libraries and Earth).

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.

Mia Ridge from the Science Museum and Tony Hirst from the Open University have both mentioned the GOOD APIs survey on their blogs:

• Ouseful.info
• Open Objects

In his post Tony also mentions the JISC Developer Happiness Days (9-13 February 2009, London). The Good APIs fully intends to have a presence at this event, possibly on the Community gatherings day (Thursday 12 February).

This is a “day of community activities based around specific software types, bringing everyone back into the systems they work with on a day-to-day basis. Pitch ideas to your fellow community members and take the opportunity to drop in on a different community session as well“.

At the moment the JISC Developer Happiness team are offereing free beds to novice developers who wouldn’t normally get funding to attend the event. Take a look!

In order to collate information the project team have written a very brief research survey asking you about your use of APIs (both providing and consuming).

If you could spare just 5 – 10 minutes of your time to fill in the survey it would be really helpful and greatly appreciated.

If you would like to be notified of the release of any documentation please fill in your e-mail address on the first page of the survey.

All data will be treated in a sensitive way and no names will be included in any of published documentation. The survey will close on Wednesday 21st January.

Thanks for your help.