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 only thing that we know for certain about the future is that things will change, and that is especially true in our industry. If your APIs are successful they will be used in ways you never had foreseen and the data you deliver will be combined with other data in very surprising ways.
photo by Bruce Denis
At the same time technology will change and what your organisation can and want to deliver to its customers will change. In order to keep relevant and to keep serving these ever evolving needs and requirements your APIs need to change and you need to know how to handle these changes.
One of the biggest difficulties developers can have when writing code that talks with an API is dealing with errors and exceptions, and translating those errors into something meaningful for their applications.
photo by Bent Jensen
Because APIs are based on different technologies and libraries, error codes are often inherited and do not make sense to whatever framework the consumer is using. Even worse is when those error codes and messages are simply passed through to the end-user without any manipulation by the application.
So, how can you make sure that all your API consumer understand your error codes and can handle them properly? If you’re offering a REST API, consumers expect your endpoints to behave like any other HTTP endpoint, so a good start is to simply follow the standards.
HTTP API authentication has evolved through many forms over the years. As so-called RESTful APIs gained popularity, a variety of methods sprung up: key passing, plain-old HTTP Basic Auth, OAuth 1.0, OAuth 1.0a, OAuth 2.0 (and it’s 40 revision) and some less-common custom schemes. With the OAuth 2.0 specification finalized, things are finally starting to settle down and coalesce around a single auth mechanism. For publicly-available APIs, OAuth 2.0 should be on your list of requirements.
According to ISO 9241-210, User Experience, or UX, is “a person’s perceptions and responses that result from the use or anticipated use of a product, system or service”. Additionally, Wikipedia has a broader definition, covering many aspects of the way users interact with a system:
[UX] involves a person’s emotions about using a particular product, system or service. User experience highlights the experiential, affective, meaningful and valuable aspects of human-computer interaction and product ownership. Additionally, it includes a person’s perceptions of the practical aspects such as utility, ease of use and efficiency of the system. — bolds added by me
So, if APIs are, by definition, Application Programming Interfaces, API User Experience can be defined as follows: