API developer experience is a relatively novel focus aimed to improve API design so it provides a seamless experience to developers when writing software. It can help increase programmers’ efficience and make it easier for developers to achieve goals on behalf of end users.
Jeremiah Lee Cohick, software engineer at Fitbit with a penchant for user experience, frames API experience in the broader developer experience (DX) field. DX encompasses many aspects of the relationship between programmers and the platform they are developing for, such as trust, education, tools, and platform usability. Specifically, he describes API experience as the UX of APIs, which ends up being a critical part of the development cycle phase dedicated to writing code. In a 2014 presentation at Web Directions, Cohick identified four key concerns that can help reach the goal of API excellence:
- Functionality: what problem the API solves and how good it is at that. An API should not only strive for effectively solving a problem, it should also solve it very well.
- Reliability: a set of non-functional requirements such as availability, scalability, stability, etc. that can help build trust and represent a necessary ingredient in driving developers to use an API.
- Usability: how well does an API lend itself to discover and learn how its functionality can be used (intuitability)? How easily does it allow developers to create tests? What support does it provide for error handling?
- Pleasure: how enjoyable is an API to use?
According to Cohick, when all those pieces fit well together they provide a great developer experience and their absence or imperfection are usually the source of pain and confusion.
Amit Jotwani, Sr. Developer Evangelist & Product Lead at Intel Mashery, says that “people who are really serious about API should care about developer experience”. He suggests ten steps towards great API experience, which :
- Keep it simple.
- Avoid marketing jargon and be clear about what developers can stop doing if they use your API.
- Simple and fast signup, which also includes easy management of API keys, service selection, etc.
- Fast setup time: ideally, only 5 minutes should be required to create an “Hello World” app.
- Fast API key provisioning to spare developers long waits.
- Clarity about costs and limitations; do not create excessive expectations; provide free trial.
- Provide stellar documentation that is complete and up to date, and avoid using PDFs.
- Provide interactive documentation, such as the Mashery API explorer and Klout interactive console to make it easier to discover and learn APIs.
- Show the code, poroviding clear and concise examples of the way an API can be used for a given task.
- Inspire developers and be available on channels such as Stack Overflow, Twitter, etc.
According to Ronnie Mitra, director of API design at the API Academy, a consulting company helping organizations to improve their APIs, API experience starts from the recognition that developers are people too. The API designer, says Mitra, should set four key goals in order to create an excellent DX:
- Facilitating troubleshooting (e.g. providing useful error messages)
- Simplifying change management (e.g. implementing an API versioning strategy)
- Improving visibility (e.g. providing log and usage access)
- Establishing trust (e.g. communicating a sense of stability and longevity)
In a talk at the Nordic APIs conference in Stockholm, Mitra proposed a frame similar to Cohick’s to help design great APIs and that has three main pillars: functionality, usability, experience. In this context, usability shifts the focus from the functionality/reliability level towards developers, aiming at making APIs easy to use. Experience concerns itself with how the developer feels about all of the interactions with an API and its providers, and builds on top of both functionality and usability.
According to Mitra, the key to providing a great API experience is to understand its audience. This can be done by defining personas representing typical API consumers.
You can’t design for usability if you don’t know who is using your API
Once personas are defined, usability aspects of an API can be evaluated along several dimensions, based on the work of Steven Clarke at Microsoft:
-
Invocation Ratio: How many calls does it take for the developer to accomplish their desired task?
-
Structure: How deep is the required data located? What is the signal to noise ratio?
-
Navigation: How difficult is it to move from one result to another? How difficult is it to locate a required datum?
-
Developer Stack Size: How many new components are needed?
-
Time to First Call: How quickly can a new user make their first API call?
-
Errors: How difficult are they to fix? What is the nature of the error? (unpredicted result, invalid input, out of sequence, etc…)
Similarly, the experience an API provides have the following aspects: engagement, pleasure, familiarity, trust, and safety, that can be used to guide the design process. Those aspects are a direct product of an API’s usability qualities.
