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.
Nice article.
You might find Rusty’s guide to interface simplicity interesting. It’s based on the premise that the more difficult it is to mis-use an API, the better it is.
“Is consistent, predictable, learnable”
I’ve been pondering this for some time, and I think you can simplify it to easy to understand. If I can understand it easily, it’s probably simple and consistent. It is probably also extensible, otherwise it wouldn’t have survived the couple of iterations that were needed to bring it to this state of easy-to-understandness.
It is, however, only one side of the coin. The other side is being easy to use. Many interfaces are sender-oriented, focusing on exposing something the programmer built to some detail, rather than being receiver-oriented, focusing on helping other programmers solve their problems.
A typical syndrome is making some arbitrary complex thing simple, while the stuff 99% of the API users actually need is unnecessarily complicated, e.g. you want to lookup a single value but first need to instantiate 7 different objects that make little sense outside the head of the programmer who made the API.
Another typical one is the unrealistic-examples syndrome. So the examples show how to retrieve one value, but in the real world everybody actually needs to retrieve 1000 values. How do you do that efficiently? No help there, unless you dig through the code and find the little loophole the API programmer himself is using but thought was too much of a hack to document.
I agree with what you say here. We’re trying to create a dead-simple way to generate, distribute or consume APIs.
This is an API profile: http://www.mashape.com/component/Image%20Pack
What do you think Ivan? We should improve some part?
Your tips have a huge value for us. Thx.
cheers,
augusto
Geek Sniper @ Mashape