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

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.