Good APIs Project

The Good APIs reports are now available from the JISC Information Environment Repository.

• Report 1: JISC Good APIs Management Report
• Report 2: API Good Practice

The final version of the reports have now been submitted. They will be posted up on the blog sometime soon.

Thank you so much to everyone who has contributed to the reports and commented on the best practice section. They may not hold all the answers but hopefully are a starter for 10.

Happy APIing!

Cartoon by Rob Cottingham, Social Signal

We are making the good practice section of the JISC Good APIs report available here on the blog for the development community to comment on. Please feel free to add any thoughts, comments and constructive feedback on the suggestions made.

This section is a version of a Good Practice report, the second of two deliverables provided to the JISC. They comprise of a number of good practice techniques for provision of and consuming APIs.

The detail of these techniques is based primarily on feedback provided from the developer community via two consultation mechanisms: an online survey of and interviews with the HE developer community.

These techniques are open to comments from the public and any feedback will be passed on to the JISC.

Intended Target Audience

This report is intended for use by Higher Education development community. It will also have some relevance for managers by providing them with a better understanding of the good practice use of APIs in the Higher Education Sector.

Licence

This report is licensed under a Creative Commons Attribution-Non-Commercial 2.0 UK: England & Wales Licence.

Quotations used in the Report

The quotations given in block quote style in this report are from the Good APIs survey. When conducting the survey it was indicated that all information would be annonymised and so all quotations are not attributed.

Contents

Good Practice for Provision of APIs

• 1.1 Plan
• 1.2 Gather Requirements
• 1.3 Make It Useful
• 1.4 Keep It Simple
• 1.5 Make It Modular
• 1.6 Follow Standards
• 1.7 Use Consistent Naming Structures
• 1.8 Make It Easy To Access
• 1.9 Let Developers Know It Exists
• 1.10 Version Control
• 1.11 Provide Documentation
• 1.12 Error Handling
• 1.13 Provide it in Different Languages
• 1.14 Make Sure It Works
• 1.15 Feedback
• 1.16 Maintain your API

Good Practice for Consuming APIs

• 2.1 Choose Carefully
• 2.2 Risk Management
• 2.3 Document
• 2.4 Share
• 2.5 Respect
• 2.6 Clarity
• 2.7 Understand Technology Limitations
• 2.8 Keep It Simple

Acknowledgements

Thanks to all the people who participated in the Good APIs survey and offered support throughout the project.

Special thanks go to:

• UKOLN Systems Team
• Pete Johnston
• Ian Ibbotson
• Wilbert Kraan
• Tony Hirst
• Sam Easterby-Smith
• Phil Wilson
• Dave Flanders

Other Versions of the Good Practice Techniques

These techniques are also available in word and PDF format as submitted to the JISC. The PDFs are linked to below, please contact the project team if you require the word document.

• Report 1: JISC Good APIs Management Report [PDF]
• Report 2: API Good Practice [PDF]

The first draft of the Good APIs report has now been submitted for discussion. Here’s is a Wordle taster of what’s in it:

Julian Cheal from UKOLN came fourth in the individual medley competition at the  JISC’s Developer Happiness Days. Delegates were given five poker chips at the start of the week, which they could give to any other delegate for being helpful (giving a talk, giving advice, offering code, etc.).  On Wednesday evening people with lots of poker chips gave them up to be counted.

The results in full were:

1. Simal Kamali  with a grand total of 38.
2. Matt Zumwalt with 34.
3. Mark Van Harmeln with 33.
4. Julian Cheal with 25

UKOLN was well represented at the event. Well done UKOLN!

The dev8d blog has some really good useful interviews that are worth reaeding.

On Monday the Good APIs project team headed down to the JISC Developer Happiness Days (dev8d) launch at Birkbeck, University of London.

This 5 day event is JISC’s attempt at getting a lot of educational software developers together to pool ideas and take part in a developer decathlon: a two-day team coding session with prizes for the best code.

On the Monday night there was a kick-off party where Dave Flaunders explained the decathalon rules and what the event was all about. There was then a TechTalkShow hosted by Paul Walk which was a debate forum for relevant issues.

After a good social outing in the many of us headed back to our accommodation. JISC offered free beds for developers at the Palmers Lodge hostel.

In the morning there were a number of lightening talks on coding methods before the launch of the decathlon.

During our time at dev8d  the Good APIs team managed to have some really useful chats with people about where they want software development to go in the education world, and how they feel JISC could help take them there. Most were very excited to have been given the opportunity to spend such a big chunk of time ” just making stuff” and realise that JISC is keen to put money into this area.

There are lots of great resources from dev8d including some really interesting five minute interviews on the blog.

• Twitter channel – http://twitter.com/dev8D
• Web site – http://www.dev8d.org/
• blog – http://dev8d.jiscinvolve.org/
• wiki – http://code.google.com/p/developerhappinessdays/

As a follow on from the Future of Technology in Education (FOTE) conference, ULCC want to get a better understanding of the communities feeling towards both cloud computing and collaboration. With this in mind, they have put together a short survey.

The survey sits nicely alongside the Good APIs survey (now closed). Thanks to the 240 people who filled it in! That’s a lot of data to work with!

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!