Good APIs Project

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]