The API hierarchy of needs is inspired by the work of Abraham Maslow, a psychologist who created a theory that explains how human needs are fulfilled — the Maslow’s hierarchy of needs.
API Hierarchy of Needs
While Maslow’s goal was to understand and explain the priorities of human needs, from breathing and feeding to self-esteem and morality, the API hierarchy of needs explains different characteristics that make an API usable.
The hierarchy of needs is a pyramid divided into five different layers that represent different characteristics that you should consider when launching and maintaining an API.
Usability
Usability is at the bottom of the pyramid because it’s the most important characteristic that will dictate the success of your API among developers.
Is your API easy to set up and use by developers? You should make sure that any developer doesn’t take more than 3 seconds to understand what your API does, 30 seconds to find the correct endpoint and 3 minutes to start consuming it (the 3:30:3 Rule, by Ori Pekelman).
Other usability aspects involve, among other things, using an appropriate authentication scheme, offering easy to use endpoint URLs, and responding standard HTTP error codes.
Functionality
Does your API work as expected? Your API endpoints should behave exactly as announced on the documentation. In situations where unexpected things happen, you should offer easy to consume error codes.
There are tools that help you test your API thoroughly, so you don’t have an excuse not to make sure what you ship really works. SmartBear and Runscope should be under your radar, if you really care about your API.
Reliability
Does your API work flawlessly repeatedly? You should care about uptime, rate limiting and throttling, to make sure that every API call is handled properly according to your usage policies. If you have a business model around your API, then you should pay extra attention to this reliability.
Again, you don’t have to reinvent the wheel. Products like 3scale offer all these tools so you can sleep better without worrying if your API is down.
Proficiency
Does your API increase developers skills? After fulfilling all the previous needs, you should provide ready to consume documentation and libraries that educate developers, amplifying their skills. If possible, offer tools that encourage discussion and participation.
You should take a look at tools like apiary.io and Swagger, that let you describe and document your API programmatically.
Creativity
The last layer of the pyramid is related with all the new things developers can build with your API. Can your API be used in unexpected ways? You should foster innovation among your API developer community so new products can be built by mixing different APIs together. If you’re too rigid about what developers can or cannot do, your API popularity will certainly decrease.
So, does your API offer all the characteristics from the hierarchy of needs?
If you enjoy this article please upvote it on Hacker News and reddit.
No API works flawlessly. I have never yet met an API that does that. If it were the case there would never be a need to improve, refactor or release subsequent versions of it.
The 3 second rule is utter rubbish. There are many APIs that require an IQ higher than the typical IQ of a web developer. The typical web developer might take 10 minutes to understand it, whereas a proper software engineer might manage it in 3 seconds.
I agree — it’s because most APIs don’t work flawlessly that we’re discussing these topics, and always trying to improve how APIs work.
The 3 second rule is a utopian goal. If you work towards it, you’ll eventually reach to a point where it takes a reasonable amount of time to understand what your API does.
Interesting article providing a sort of path to follow when building an API with the right step at the right time.
Thanks 🙂
Interessant to compare with other API pyramid of needs http://api500.com/post/27366085761/developers-api-pyramid-of-needs-what-do-we-expect
Great talk at APIdays Mediterranea by the way where you explained your vision about this pyramid.
Thanks for sharing the link, so we can all see different perspectives!
The pyramid I presented at APIdays was not this one. It was an adaptation of this one but from a customer (not a developer) point of view.
Pingback: Bridging the Gap Between APIs and Customers | Bruno Pedro
I disagree with placing usability above functionality and reliability in importance. An API actually working is much more important to me. For example, the Twilio API has great usability but the biggest frustration I’ve had with it is when features did not work. With the AWS API, the error codes it gives are pretty much useless.
Placing Usability at the bottom of the pyramid is generating an interesting debate among several people.
If your goal is to make your API successful, you need to be able to evangelize developers into using it. If developers cannot even use it, it really doesn’t matter if your API works at all, does it?
And conversely if your API has broken features or has bad uptime it doesn’t really matter how usable it is. A pyramid model which places one of several important needs over others might not be the best idea. A better model would be one which places equal importance on needs such as usability, functionality and reliability.
“Can it be used in unexpected ways?” That really would worry me. Your argument is absolutely valid on one hand. The more versatile, open and applicable the API is the more attractive it is for the developers/users. On the other hand if you open up your application giving access to all internal features you did not even have ideas how could be used, you may end up with an application that you can not develop without breaking backward compatibility.
API should be designed with the open/close principle in mind. You model is static, looking at the values the API can deliver for a certain version. Looking at the API with a dynamic view is more important: what value can your API deliver during the life time of the domain and you application supporting that domain.
I wouldn’t worry so much about the possibility of breaking backward compatibility. If things are done the right way, you should offer API versioning (http://apiux.com/2013/05/14/api-versioning/), meaning that there’s no way to break things.
I agree with your way of looking at the API with a dynamic view — thanks for sharing it.
Pingback: API Hierarchy of Needs | API Magazine: About AP...
Pingback: API Hierarchy of Needs | Software Development |...
Pingback: Applying Psychology to APIs: the Best of API Hierarchies of Needs