Good APIs Project

Now that the project completed and the reports published, this blog is closing down.

During the blogs life we made fifteen posts making various announcements about the progress of the report. We created 29 Pages in all which were used to collect comments on particular areas. These comments were in addition to the original survey that was carried out using Survey Monkey on which we had 234 responses.

The blog will remain visible for the indefinite future but will be frozen in terms of adding new content and viewers will not be able to add any further comments.

Thanks

Marieke Guy

A number of IntroByte briefing documents based on the Good APIs project work have now been added to the UKOLN Cultural Heritage Web site:

Briefing Documents on APIs (Permalink)

• An Introduction To APIs, (briefing 46):
  [About] – [MS Word]
• Best Practices For APIs: Planning (1), (briefing 73):
  [About] – [MS Word]
• Best Practices For APIs: Planning (2), (briefing 74):
  [About] – [MS Word]
• Best Practices For APIs: Planning (3), (briefing 75):
  [About] – [MS Word]
• Best Practices For APIs: Planning (4), (briefing 76):
  [About] – [MS Word]
• Best Practices For APIs: Consuming (1), (briefing 77):
  [About] – [MS Word]
• Best Practices For APIs: Consuming (2), (briefing 78):
  [About] – [MS Word]
• Best Practices For APIs: Consuming (3), (briefing 79):
  [About] – [MS Word]

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).