Just recently the studies around http driven or “web APIs” has started to appear. Academic research is often lagging behind in some topics - this is one of those. The study of API usability has often focused on the programmers who use A​PIs in their own code, known as ​API Users.​ The developer experience (DX) is significantly impacted by the quality of the APIs they must use. However, the usability that these programmers experience with an API ultimately stems from how well the API and its resources were designed in the first place. Very little attention so far has been given to the API design processes or to the ​API designers who are making these design decisions.

This time I’ll discuss matters which are dropped into two slices in the 360 DX piechart

You can ruin a API before you even start to implement it. Jumping straight to implementation is the mother of all fuck ups with APIs. A lot of people evangelise the technical best practices to gain great API and developer experience. I disagree. That is not where you ought to begin. Best practice requires testing an API with users early, even when the API is not yet implemented or even fully designed.

  1. You should first understand why it will be built, what are the use cases, what are the painpoints it will solve/relieve (problem domain).
  2. Then you design it. (solution domain)
  3. Test the design with actual consumers. If not possible, do the API Peer Review at least internally.
  4. Then you think about the details of the implementation and scalability, fit to architecture etc.
  5. Then you implement it, QA and security final check. (combining problem and solution domain)
  6. Improve based on feedback
Great API requires a lot more than great implementation, which is the manifestation of the wisdom gained in previous steps.

Skills and organisational practices

API designers must have a strong understanding of software engineering, but ​also have the ability and personal drive to stay focused on their user’s perspective as their primary goal. API design is recognized as a difficult and specialized skill with few training resources, so more training material is needed. A good API designer needs an intuition for user experience, this may be trained by giving interested developers exposure to basic user experience testing and usability methods that have been well established in UX. (Murphy et al, 2018).

The availability or lack of API designers, is twat easily results to non-optimal situations. Developers who are great at implementing the APIs also do the design. Occasionally that works well and depends of the developers ability to approach the design from consumers point of view.

API guidelines published online by various organizations are the primary authoritative source for design standards and practices. API guidelines, which not all designers actually read the entirety of their company’s guidelines, use it as a general-purpose reference material to look up specific design questions as they arise. Designers often have multiple competing design concerns and constraints to balance during API design, making following ​all guidelines much harder than it might appear. Specifically, new designers struggle with knowing the relative importance of different guidelines, and must learn through mistakes when to adhere or deviate from a rule.

Some companies enforced their API guidelines through the use of code reviews and “linter” tools that check for specific guideline requirements. The purpose of this enforcement is to ensure a base level of API usability across the company, and also ensure API users have a ​consistent experience if they use multiple APIs across the company to avoid each API having its own learning curve.

Whomever designs the API is responsible for figuring out their API users’ needs and keeping those needs central to the design process. Ideally, API design should be done by an interdisciplinary team, however the challenge remains of teaching expert software engineers enough user-centered design and teaching expert UX designers enough software engineering that these two disciplines can work effectively together.

Poor quality “bottom-up” API design occurs when, lacking real use case data, the engineering team designs around what is most straightforward to implement, which means that the API design mirrors much more the underlying ​implementation of the API than how customers want to use it. Before getting too far into construction details of the API (the things that are covered in API design guidelines) like naming, pagination, etc., it is critical to check your team’s understanding of the API’s real life client use cases, since it will often be difficult or impossible to change these later. This can be achieved by getting users involved early on in the design process and continually obtaining feedback from them throughout this process. (Murphy et al, 2018).

Cornerstones of API design

According to research done by Stylos and Myers (2017) the basic qualities basic qualities of an API are its usability and its power. It must be noted that the mentioned research is about APIs in application level, not for example http driven APIs. Nevertheless the two qualities can be described as follows.

Roughly, “usability” refers to the qualities of an API that affect its use when creating and debugging code, while “power” refers to limits of the code that can be created. Usability includes such attributes as how easy an API is to learn; how productive programmers are using it; how an API prevents errors; how simple it is; how consistent; and how well it matches its users’ mental models.

Power includes an API’s expressiveness (the sorts of programs it can create); its extensibility (how users can extend the API to create convenient user-specific components); its evolvability for the API designers who will update the API and create new versions; its performance (in terms of speed, memory and other resource consumption); and the robustness and bug-freeness of the API implementation. The usability mostly affects API users, though the error prevention affects the consumers of the resulting products. The power affects mostly API users and product consumers,though the evolvability affects API designers.

While the attributes above individually affect whether and how users adopt an API, there are also higher level issues that affect adoption. For example, one phenomenon is that of “death by 1000 paper cuts”: even if they do not have large problems, APIs can be unusable because of many small ones, such as multiple minor lapses in consistency or simplicity. On the other hand, a positive phenomenon is that of a “self-documenting” API: this is an API with enough positive usability attributes that users can figure it out as they go, and rarely if ever have to refer to the documentation. The latter is the dream come true for all API providers.

self-documenting API has enough positive usability attributes that users can figure it out as they go, and rarely if ever have to refer to the documentation

Problem with the usability of APIs is often due to same person doing the design and implementation

Evaluate before implementation

You can design API throughly and try to make it perfect in the office. That rarely results to optimal solution. Running a usability study of a specific API before it is released, using programmers representative of the target audience and the most common programming tasks that the API is intended to support, is an effective technique for detecting non-obvious usability issues with APIs and improving the usability of the released APIs. (Clarke, 2004)

The most obvious test is to involve the consumers to the process as it was discussed above. In higher level before the design should be evaluated with different approach. API Design Guides are manifestations of these higher level analysis and lessons-learned from the past.

What’s the cognitive burden to use your API

The cognitive dimensions framework is a broad-brush evaluation technique for interactive devices and for non-interactive notations. It sets out a small vocabulary of terms designed to capture the cognitively-relevant aspects of structure, and shows how they can be traded off against each other. Cognitive Dimensions Framework was designed to evaluate programming language environment usability, but has previously been adapted to evaluate API usability as well (Clarke 2005). The cognitive dimensions framework for example measures simplicity via the dimension called work-step unit which is a measure of the quantity of user code required for a single unit of work, or step.

An example is how to calculate sum with different solutions: from C to spreadsheet tools. What it takes to get *hit done? (Green and Petre, 1996)

When it comes to http driven APIs, it’s easy to see that libraries are at the right and raw APIs driven approach on the left. Notable is also that on the right the level of abstraction is higher than on the left. APIs themselves are abstraction level, so this is getting really abstract :)

Http driven APIs are languages agnostic eg they are not normally designed to any specific programming language. Of course some of the design choices such as how lists are presented are easier to use in some programming languages. For example response set might be optimised for node driven apps. Now consider a new customer taking first steps with your API. The question is how much cognitive burden does it require to get started? Do they need to learn use of some framework libraries before they can use your API? Can they just call it as is? Some kind of basic skills in the selected programming language is expected (or has to be learned) to be able to call your API from it and then process the response which might contain list of objects and attributes. The more custom style of processing is needed the bigger is the burden.

This Cognitive Dimensions Framework seems to be something that deserves a more thorough review and more time to discover how it could be used in API evaluation at different steps of API development.

After release

Feedback about APIs can be surprisingly hard to gather and interpret. On the other end of the spectrum is internal APIs, where the team has good access to talk to their users directly and with the added benefit of being able to look at their users’ code. Designers of public APIs have little direct access to their users and typically have a far larger user base. An exception is large enterprise users of a public API, who more often have a direct form of communication with the team.

For web APIs, server-side metrics offered counts about which API were most often used, but only vague clues about use cases or usability. Designers often say that counts of “how often is this API method called” are often unhelpful to infer real use cases, since it is unknown what the programmer does with the data once they receive it from the API.

For public APIs, there are often ample examples of usage on Github and many programmer questions reported on Stack Overflow, but it can be difficult to identify what is useful. A major challenge is that there are no tools available for API teams to consume community data in aggregate. The most reliable source of public feedback was reported to be GitHub issues on public API repositories (Murphy et al, 2018).

Tools for designers are focused on wrong things

Yet all the API design tools are focusing on the technical aspects (specs) of the API. We should have not so specs and validated spec driven “design” tools for API designers. Tools which enable the designer to get feedback of cognitive burden for example. It could “lint” the API design against machine readable API Design Guidelines instead of the designer checking those manually. The tool should enable aggregation of feedback to iterate the design. In brief focus less on the spec and more on the design.

Some more to read from 100 Days DX