So, you want to provide an API for the world to use?

Canonical

on 7 December 2010

I conducted 5 qualitative interviews with developers and here are some findings.

You have two problems. The first problem is to design the API. The second is to help people learn to use it.

Great API design

Is consistent, predictable, learnable. You are creating an API that developers will interact with. In the same way that a graphical user interface (GUI) might use visual design to provide users with a language to predict and learn behaviours, an API can use naming and format.

“I think like the word I would use for a good API is predictability…yeah – make intelligent guesses there should be no surprises when I move to new features it should behave basically the same way”

“‘guessability’ is the most important thing for the API and that comes from consistency.”

“some APIs are unnecessarily complex in the sense that they give you multiple ways of doing the same thing or an API where you can see a list of your friends and also a list of messages, both are lists but some APIs would do both lists differently”

“there is an idiom to a particular API and then you can guess how to use things. A poorly designed API is where that is inconsistent so you just have to google and hope for the best.”

Gets better.You will need to iterate on an API, make sure you can do that and support the people who have invested time into using your API.

“They should be designed so they can be easily extended. [You don't want to see]Multiple versions of an API and have it break on you…you don’t want to work with something that will be phased out.”

“Last.fm was really poorly maintained”

Great API documentation

Has an overview What does this API do?

“There will be high level description of the capability which needs to be presented in a feature way and then the methods”

Is concise and logical: By all means explain what Rest is but don’t let that information for a beginner obscure access to information for the more experienced developer.

“Google is well documented but there is a lot of information and you have to read a lot to find the answer”

“it is easier to have things narrowed down to 2 sentences rather than why it was like that and why it was decided. It just has to do what I want it to do; the rest doesn’t interest me.”

Uses navigation to expose content

“Well I mean as soon as you have clicked on one of these things on the Flickr one you are in back button land…”

Has tutorials

“If I am starting from scratch I have to look at tutorials”

More support

Make sure people have ready access to examples

“if I find some sample code or code snippets that is for me like heaven, I can take it and adapt it”

If you don’t provide them on your site then people are likely to Google for them.

Try before you buy
Two participants highlighted APIs that provided tools to try them before going through the effort of getting keys or authenticating in any way.

“what is probably more important [than examples] is that you have some facility for testing the API yourself.”

“Facebook needs keys and you have to jump through lots of loops to even try it”

“the nice thing about the Flickr API – there is a page where you can test the API”

Give people access to the code.
Easy for open source APIs.

“Being able to inspect the code is useful.”

“I am looking for a language I can easily read”

Before you ask, no it doesn’t make any difference what type of API. The only exception to this is the “try before you buy” which only applies to web APIs.

Talk to us today

Interested in running Ubuntu in your organisation?

Newsletter signup

Select topics you’re
interested in

In submitting this form, I confirm that I have read and agree to Canonical’s Privacy Notice and Privacy Policy.

Related posts

Design and Web team summary – 28th October 2020

The web team here at Canonical run two-week iterations. This iteration was slightly different as we began a new cycle. A cycle represents six months of work....

Build a Raspberry Pi Desktop with an Ubuntu heart

On the 22nd October 2020, Canonical released an Ubuntu Desktop image optimised for the Raspberry Pi. The Raspberry Pi Foundation’s 4GB and 8GB boards work out...

Dell brings new Intel 11th gen Core processors to the XPS 13 Developer Edition

This week, Dell announced the availability of its XPS 13 Developer Edition, preloaded with Ubuntu 20.04 LTS, has been updated with Intel’s® new 11th...