Good APIs Project

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.

Here is the Presentation given at the CETIS conference.

Have a Good Christmas and New Year Everyone.

Good APIs project went along to the Mashed Libraries 2008 event on the 27th November 2008 at Birkbeck College, London. This event was an attempt to get HE/FE library developers together and trying out new things. It was conceived by Owen Stephens of Imperial College and sponsored by UKOLN.

A number of photos are available on Flickr and several blog posts have already been written about the day.

• Paul Walk
• Andy McGregor
• Jo Alcock
• Clari Hunt
• Richard Wallis (Panlibus)
• Tony Hirst
• Edith Speller
• Chris Keene
• Paul Stainthorp (also see Paul’s live blog from the day)
• Owen Stephens

The Ning network is also still available

Good APIs project was represented at the recent CETIS Conference 2008 when Brian Kelly and Marieke Guy co-facilitated a half-day session on Innovation in a World on Web APIs.

The session was run as an unconference and attendees were encouraged to contribute.

In the first part of the session people were asked to talk about what they are currently working on:

• Ian Ibbotson talked about the SWORD API
• Tony Hirst gave a live constructed on the fly a prototype using Google Spreadsheets to harvest data contained in a table in a Wikipedia page (lists of cities in the UK), fed this into a Yahoo Pipe (Geo locate cities and create an RSS feed) and then fed this into Google Maps.
• Sam Easterby-Smith demonstrated PROD – a directory and monitoring tool for JISC funded projects.
• John Kleeman showed Questionmark’s SOAP API

After coffee the second part of the session was spent looking at the future. This also involved exploring best practices for Web APIs.

Feedback from the session is available from the session wiki. Further resources and handouts are available from the UKOLN Web site.

Tony Hirst has also provided some useful definitions and pointers on his blog.

The ‘Good APIs’ project aims to provide JISC and the sector with information and advice on the factors that encourage use of machine interfaces, based on existing practice.

The blog will provide a central link to resources created during the project, information about the project and final deliverables.

It will also allow those interested in issues relating to the use of APIs in HE  to comment on discussion areas and findings.

If you have a question, suggestion or comment about the project please get in touch.