Good Practice for APIs

April 15th, 2009 — Marieke Guy

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

Good Practice for Consuming APIs

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.

Posted in goodpractice, report. 7 Comments »

7 Responses to “Good Practice for APIs”

  1. Frankie Roberto Says:
    April 17th, 2009 at 4:42 pm

    Any chance you produce this as a single-page report? Or a PDF?

  2. Marieke Guy Says:
    April 20th, 2009 at 9:31 am

    Hi Frankie,

    Yes, this is available in the form of a report too. There is also a much longer report covering other areas such as background to API use, benefits and challenges of API provision, problems when using third-party APIs, case studies and recommendation of future work.

    We’ll make these available as soon as they’ve been formally passed over to JISC and the go ahead is given.

    Marieke

  3. Christopher Wood Says:
    April 30th, 2009 at 10:19 am

    Thanks – this is a really useful document – have downloaded the PDF to share with my team. Chris.

  4. Cultural Heritage » Blog Archive » Elsewhere on UKOLN Blogs: April 2009 Says:
    April 30th, 2009 at 2:57 pm

    [...] Good Practice for APIs [...]

  5. Anthony Leonard Says:
    May 7th, 2009 at 10:32 pm

    Hi Marieke,

    This is a much needed project. Good APIs are crucial for end-users as they enable the holy grail: “joined up” services.

    Like anything made of joined up components (buildings, cars, electric kettles, etc) the key to engineering success is: standards, standards, standards.

    I don’t think this can be emphasised enough. Buildings that are lovingly created by craftsmen are rare and often leak. Those that follow standards don’t. So it is with IT services.

    Anthony.

  6. Cultural Heritage » Blog Archive » APIs and the Cultural Heritage Sector Says:
    May 8th, 2009 at 9:17 am

    [...] and outcomes are transferable to the cultural heritage sector. One such outcome is the list of good practice techniques for API creation and consumption. The techniques are currently open for [...]

  7. Balbir Barn Says:
    May 13th, 2009 at 7:01 pm

    What makes a good API? Here is a selection of guidelines from the ACM: DOI:10.1145/1506409.1506424

    Obviously:

    An API must provide sufficient functionality for the caller to
    achieve its task

    An API should be minimal, it must not impose unnecessary inconvenience to the caller. (use less parameters, get the granularity down) Don’t make an API call – a composite function.

    General-purpose APIs should be policy free – Specialist APIs should be policy-rich.
    (here APIS presume the use-case under which the API will be consumed)

    APIs should be designed from the perspective of the caller

    APIs should be documented before they are implemented

«

»