Your submission was sent successfully! Close

You have successfully unsubscribed! Close

Thank you for signing up for our newsletter!
In these regular emails you will find the latest updates about Ubuntu and upcoming events where you can meet our team.Close

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


on 7 December 2010

This article is more than 13 years old.

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

“ 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

Get the latest Ubuntu news and updates in your inbox.

By submitting this form, I confirm that I have read and agree to Canonical's Privacy Policy.

Related posts

Canonical releases Landscape 24.04 LTS

Landscape 24.04 LTS is Landscape’s first LTS release, with a modernised backend, web portal, snap management, and repository management features.

Canonical releases Ubuntu 24.04 LTS Noble Numbat

Canonical’s 10th Long Term Supported release sets a new standard in performance engineering, enterprise security and developer experience.

Ubuntu Desktop 24.04 LTS: Noble Numbat deep dive

Learn how Ubuntu Desktop 24.04 LTS is built to empower open source developers and deliver innovation for the next 12 years.