Blog

- May 18, 2017

In our previous post we have discovered the two perspectives of API design but whatever the chosen design perspective, there’s a key concept to keep in mind when designing APIs: Consistency. But what does really means being consistent in API design and why does it matter? This is what we will talk about in this post.

What is consistency and why it matters

Would you be able to use easily and safely such a strange air cooler controller with these four strange buttons and showing temperature in Kelvins, Celsius and Fahrenheit degrees?

No, because this device is totally inconsistent with what you know about temperature control devices and it’s not even consistent with itself.

If we take a look at the consistent word’s definition in a dictionary, we’ll find things like coherence, free from variation or contradiction, conformity to character. This is exactly what everyone expects from anything. Everyone expects a spade to be called a spade anytime and anywhere.

Such a device should present temperature in a single unit and this unit should be the one used in the country where this device is. Buttons forms should mean something for the user like up and down arrows for example.

It’s exactly the same thing with APIs. Working with a REST API, everyone expects a GET request to retrieve data not delete them, everyone expects a 200 status to mean everything went OK, everyone expect a href property to contain a string which is a URI or URL, everyone expect properties containing temperatures to use the same unit.

Surprising user by being inconsistent is a terrible idea. Without consistent design the users of an API will at best lose time to understand how to do things and what’s happening; and at worst decide not to use the API or misuse it.

The four levels of consistency

Consistency in API design is more than just using GET HTTP verb ou 200 HTTP status wisely, it can be split in four levels:

  • Common: Being consistent with the world
  • Local: Being consistent within an API
  • Transversal: Being consistent across APIs
  • Domain: Being consistent with a specific domain

Let’s see what consistent API design means for each of these levels.

Common consistency

This level is the most known and the most obvious when it comes to consistency in API design. It’s about being consistent with the world, consistent with a widely shared knowledge.

For a REST API it will be to at least to fully respect the HTTP protocol usage shared across all the web. It can consists also of following some common practices like the URI template /resources/ID/sub-resources/ID. And it can be a good idea to copy what some famous API providers do.

It’s also being consistent in the data format used by the API: timezone, currency, units, … everybody expects to get the formats they understand.

By doing that users can know instinctively how to use an API without even reading the documentation.

Local consistency

Local consistency is about being consistent within an API. An API designer will have to make choice about how to name properties and how to structure data and URIs for a specific API.

If the same data is shown in various resources, it would be wise to always use the same name and the same type. If camelCase is used to name properties, don’t dare to use spinal-case for some of them. If a prefix or suffix is used to give hint about the property types or conceptual meaning, always use it and always use it the same way. If an error response contains an error code and message, never dare to only return a message.

By doing so, users can predict how any endpoint is working or the meaning of any data just after starting to work with an API.

Transversal consistency

Transversal consistency is about being consistent across an organisation. It’s basically applying local consistency to all APIs or all APIs of the same type within this organization.

Consistency in API design is mandatory in this micro-services era where systems are composed of many independent software bricks talking to each other through APIs. The more an organization’s APIs are consistent with each other the more it will be easy to work with them (aggregation, orchestration, monitoring, …). After having used one API, a user will be able to use any other one from this organization instinctively.

Domain consistency

Domain consistency is probably the less known side of consistency in API design, it’s about conforming to a domain point of view or to a standard.

It goes from choosing data representation like country codes using the ISO-3611 format to following the Acord Model to structure data when working with insurance data or more simply reuse shared schemas available at schemas.org.

Being domain consistent will ease the use of your API for domain expert but be careful of your targeted audience because you may have to choose between consistency and usability.

Save APIs, design consistently

Consistency is definitely a key concept that will ensure an API’s usability and adoption, an API MUST be free from variation or contradiction. And not only an API has to be consistent with itself, it must be consistent with more or less widely shared knowledges and practices.  

In our next post, we’ll see how to ensure this consistency.