APIs need to be both machine and developer friendly
The importance of user experience (UX) is widely recognized by technology companies. UX has become one of the key success factors for products. By definition from Nielsen and Norman, UX covers “all aspects of the end-user’s interaction with the company, its services, and its products.” If your product is an API (application programming interface), the users interacting with your product, and your company are developers and you need to be considering developer experience (DX).
Creating a positive developer experience may seem like the easiest goal ever. After all, you are catering for people “just like yourself”. However, if you take a step back and look at your API with the eyes of a newcomer, you will realize that the people who use your API are not you. They will not have the tacit knowledge you have about your API or its design.
The API consumers will make assumptions, but those assumptions are most likely different than you expect. If you ever have had to use someone else’s code, you know how easily get lost in assumptions, design decisions and missing documentation. Furthermore, developers’ primary goal is not using your API. Rather, they use it to make (their) life easier in some way: they need to achieve an end-user goal or want to avoid duplicate implementation work.
API DX can be divided into four key areas: functionality, reliability, usability, and pleasure.
Functionality is the most basic factor: if your API is not useful, no one will care about it. An API becomes interesting, when it provides useful data or functionality you cannot access in any other means. Or maybe it does something the developers have done before, but in a more effective or simple way.
Reliability is another threshold factor. Developers need to be able to trust that your API is available and stable. Developers don’t want to risk the fact that their end users might see missing functionality. Your API also needs to scale when there is a popularity spike.
Usability sums up how easily and intuitively the developers can use your API. Is it easy to learn? How long does it take for the developers to make their first call? How many calls do they have to make to accomplish one goal? How usable is the structure of the responses they are getting?
The top of the DX pyramid, pleasure, goes beyond having a well-designed, useful, stable and intuitive API. If your API is truly awesome, it feels like an obvious solution or choice. Also, any other interaction besides using the API works without hiccups. The API offers registration and setup steps that don’t make you sweat and curse. It also provides developers with great up-to-date documentation and means to get help easily. A pleasurable API is not just a well-designed product, but also a well packaged one. One that is enjoyable to unbox.
You can’t design for usability, if you don’t know who is using your API. (Ronnie Mitra)
One of the key success factors in any UX design is empathy. You need to imagine what developers are trying to achieve and how they are able to achieve their goal given the information and tools they have at hand. Get to know who your users are. Leave the comfort of your office and talk to the users to understand their needs. Another good step towards empathy is “eating your own dogfood”. As a minimum, test the API yourself before publishing it. Even more optimally, you or your organization should use your API.
Consider also using an API management solution. It can help you to minimize developer setup related tasks and offer a unified developer experience. An API management tool can cover many of the required facets for you — some you might forget or even not realize are needed.
Why is developer experience so important? It does not matter if you are a researcher writing publications, a city planner defining the next smart city, a VR developer exploring immersion or an investor looking at IoT, technology is all around. The latest trend is going heavily for APIs, which are increasingly used by developers to build complex systems. Therefore, your API should offer the best DX possible.
Text originally published in Mindtrek 2016 blog.
