People Will Love Your Consistent API Design

This is an “adapted” excerpt of “The Design of Web APIs” by Arnaud Lauret. If you would like a copy of his book, use code: blstoplight21 at this link to get 35% off your own copy!

Have you ever felt tremendous pleasure when using an unfamiliar object or application for the first time? You know, when everything is so intuitive and easy that you feel outrageously smart as you discover on your own all of its possibilities?

This is possible not only because you are actually outrageously smart, but also because the thing you are using has been designed to make it totally predictable.

What about designing such an awesome API? What about designing an API that users will be able to use instinctively without thinking about it, even if it is the very first time they’re using it?

How can we do that?

The first step towards creating totally predictable APIs is designing consistent APIs.

Experiencing consistency in the real world

If you encounter a washing machine like the one shown below, with a button showing a triangle icon oriented from left to right, you can guess this button’s purpose easily. Why? Because you’ve already seen this icon on various media players.

Since the mid-1960s, all media players have used such an icon. From obscure DCC (Digital Compact Cassette) players to compact disc players and software media players, each one of these devices uses the same triangle icon for the Start Play button. Therefore, you can guess that this button starts the washing machine.

I’m sure you know what the standard Pause button looks like too. What if a media player does not use this standard icon for its Pause button? Users will be puzzled and will have to make an effort to understand how to pause the audio or video that’s playing.

What is true for real-world human interfaces is also true for APIs. It is essential to keep the design of an API consistent—to make it predictable.

Let’s see a few examples of how consistency matters in API design.

Choosing consistent names

Data is at the core of APIs—resources, parameters, responses, and their properties shape an API. And all of their meanings, names, types, formats, and organization must be consistent in order to help consumers understand these data easily. So, designing consistent APIs starts with choosing consistent names, as shown in the figure below.

In a Banking API with inconsistent naming, an account number could be represented as accountNumber for the get accounts goal’s result, as number for get account, and as source for the money transfer goal’s input. Here, the same piece of information in three different contexts is represented with three totally different names. Users will not make the connection between them easily.

Once users have seen an account number represented as accountNumber, they expect to see that piece of information always represented by accountNumber. People are used to uniformity in design. So, whether this property is part of a fully detailed account listing, a summary of the account list, or a path parameter, an account number must be called an accountNumber.

When choosing names for various representations of the same concept, take care to use similar ones. When used for a money transfer to identify the source account, the original name should remain recognizable. But it can be altered in order to provide more information about the nature of the property; we might call it sourceAccountNumber, for example. Now consumers are able to make a connection between these properties and guess that they represent the same concept.

That also works for unrelated data of a similar type or for representing similar concepts. For example, balanceDate, dateOfCreation, and executionDay all represent a date, but the first one uses the suffix Date; the second one, the prefix dateOf; and the third, the suffix Day. Using a generic suffix or prefix in a name to provide additional information about the nature of what is named is a good practice, as long as it is done consistently. Here, the good design uses the same Date suffix for all dates, but you can choose another solution as long as you remain consistent.

Choosing consistent data formats

Even consistently named, a property can still be subject to inconsistency, as shown below.

An account number could be represented as the string “0001234567” in the `get accounts` result, as the string “01234567” for `get account`, and as the number 1234567 for the money transfer goal’s input. Such variations will inevitably cause bugs on the consumer side. To fix them, consumers must standardize these different representations and know when to convert one type or format to another to use it in a given context.

People and software don’t like to be surprised with such inconsistencies. Once consumers have seen the first accountNumber property as a string with a specific format, they expect all other account number representations to be strings with the same format. Even if they have different names, different representations of the same concept should use the same type and format.

Choosing a data type or format can also have an overall impact on the API. How do you think consumers will react if they see the balanceDate of a bank account as an ISO 8601 string (such as 2018-03-23), the creationDate of an account represented by a UNIX timestamp (such as 1423267200), and the executionDate of a transfer as YYYY-DD-MM date (such as 2018-23-03)? They won’t like it because it’s inconsistent.

People seek global uniformity in design. Once consumers have seen one date and time property represented by an ISO 8601 string, they expect all date and time properties to be ISO 8601 strings. Once a data format has been chosen for a type of data, it should be used for all representations.

Organizing with consistency

Naming and formatting are not the only API design matters that require consistency.

What’s the problem with the two URLs and the two data structures shown in the figure below? Their data organizations are inconsistent.

The /accounts/{accountNumber} and /transfers/delayed/{transferId} URLs don’t have the same organization. The /transfers/delayed/{transferId} URL introduces an unexpected level between the collection name and resource ID, making the URL harder to understand. We could use /delayed-transfers/{transferId} instead, for example.

Each level of a URL should always have the same meaning. Once consumers are used to a data organizational pattern, they expect to see it used everywhere. Again, this doesn’t only apply to URLs; data organization in inputs and outputs can present patterns too. In the bottom part of the figure, the elements of two collections are represented in two different ways. If every collection resource you have designed so far is represented by an object containing a property called items, which is an array, do not dare to design one as a simple array. Why? Because consumers will be surprised by this variation.

Consistency, the first step towards predictability

A consistent design is free from variation or contradiction; it helps to make an interface intuitive by taking advantage of users’ previous experiences. An inconsistent design introduces variations or contradictions that make an interface harder to understand and use.

Once a design choice is made, stick to it. To keep your design globally consistent, define conventions and strictly follow them. Naming and formatting/organizing conventions can be defined for properties, query parameters, paths, data structures, and more.

Integrate linting and custom rulesets using applications like open source Stoplight Spectral or the Stoplight Platform to check your API designs. This process ensures that your conventions are automatically checked and enforced, saving time and promoting consistency throughout your entire API program.

Even though we only scratched the surface of how to create consistent and predictable APIs, these examples should put you on the right track. Thanks to a consistent design, users will be able to use an API instinctively without thinking about it, even if it is the very first time they’re using it. They love that.

If you want to learn more about designing APIs, and especially how to create totally consistent and predictable APIs, read The Design of Web APIs.