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

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]

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

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

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

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/

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!