From The Design of Web APIs by Arnaud Lauret

Why should we care about the design of an API? It’s quite simple. What do you do when you use an everyday thing, whether it’s a microwave oven, a web site, a mobile application, a TV remote or an ATM? You use its interface.

Save 37% on The Design of Web APIs. Just enter code fcclauret into the discount code box at checkout at manning.com.

IMPORTANT

For the purposes of this article (and the book it has been excerpted from), when an API is referred to, this is understood to be a web API. It might be helpful to consult web design in fort lauderdale if you wanted to gain a better understanding of web API.

What do you do when you use an everyday thing you’ve never used before? You take a close look at its interface to determine its purpose and how to use it based on what you can see and your experience. And this is where design matters. An API is an interface which is supposed to be used by developers within their software. Design matters whatever the type of interface and APIs are no exception.

Figure 1 A cryptic device’s interface

What could be this UDRC 1138 device? What could be its purpose? It isn’t easy to guess by looking at its name, maybe its interface can help us. Six unlabeled buttons exist with unfamiliar forms that don’t give any hint about their purposes. The LCD display screen shows four, also unlabeled values. I’m unfamiliar with all these units. And there’s even a warning message telling us that we can input wrong values without safety control. This interface is hard to decipher and isn’t engaging. Let’s take a look at the documentation to see what this device could be.

Figure 2 A cryptic device’s documentation

The UDRC 1138 is a universal drone remote controller. Well, it sounds interesting.

It allows a user to control speed, elevation and orientation of any drone using the 6 buttons. This is insane; how is a user supposed to use that easily? Buttons shapes don’t mean anything and they aren’t even ordered correctly!

It works only if the drone’s within a 50 meter (164 feet) range, the LCD screen shows ground distance and height. Wait, what? The user has to calculate the distance between the remote controller and the drone based on the information provided on the LCD display screen?! This is a total nonsense. I don’t want to use the Pythagorean Theorem on the fly; the device should do that for me.

The LCD description puzzles me too. I’m unfamiliar with aeronautic units of measurement but I sense there’s something wrong with the chosen ones. They seem inconsistent. Mixing feet and meters? And in all the movies I’ve seen about airplanes, they use feet to measure height and nautical miles to measure distance, not the contrary. This is definitely not engaging. Would you buy or even try to use such a device? Probably not.

Hopefully, such an overly poor designed device’s interface couldn’t exist. Designers couldn’t create such thing… Well, maybe, but and even if it was possible, the quality department would never let it go into production…I hope. Let’s face the truth, poorly designed devices, everyday things with poor designed interfaces, go into production. Think about how many times you’ve been puzzled or grumbled when using a device, a web site, or an application because its design was flawed? How many times did you choose not to buy or not to use something because of its design flaws? How many times did you restrain the way you use something that you needed to use because its interface was incomprehensible? A poorly designed product may be misused, underused or not used at all. It can be dangerous for its user and even the organization which created it, and this is no different for websites. Highlighting why it’s important to employ a professional, such as http://rorymartin.com/, to ensure the API is operating optimally at all times – both front and back end.

And on top of that, once such a physical device goes into production, it’s too late to fix it.

Such terrible design flaws aren’t reserved to everyday interfaces.

Figure 3 Getting UDRC 1138 status via its terrible API

Unfortunately, APIs can also suffer from this flawed design disease. Poorly designed APIs can look exactly like this URDC 1138’s interface. A poorly designed API can be a real pain to understand and use; it can have terrible consequences.

NOTE

Keep this in mind!

API design has more to do with user interface design than programming.

How do people choose a public API, an API as a product? They go to the developer portal to read the documentation and analyze the API to understand what it allows and how to use it, to evaluate if it fits their needs simply. Even the best documentation won’t hide API design flaws, which makes the API hard or even dangerous to use. Therefore, these potential users, these potential customers won’t choose this API. No customers, no revenue. It may lead to a company’s bankruptcy.

What if some people decide to use this flawed designed API or have no other choice and must use it? What will happen? It will increase the time, effort and money needed to build a software using this API. The API may be misused or underused. The API’s users may need extensive support from the API provider, therefore raising costs. If the API is a public one, its users may complain publicly or stop using it, resulting in less customers and less revenue for the API provider. If it’s a private one, losing money on these projects may hinder the company strategy. After too many failures, it may even result in an “APIs aren’t for us” attitude which could doom the company in the long run.

Flawed API design may lead to the creation of security vulnerability in the API. Exposing sensitive data inadvertently, neglecting access rights and group privileges, the list goes on. What if people decided to exploit such a vulnerability? This is not science fiction, it’s happened.

Thankfully, in the API world, it’s possible to fix poor API design after the API goes into production, but it comes at a cost. It takes time and money for the provider to fix a mess and may also seriously bother the API’s consumers.

NOTE

Keep this in mind!

Poorly-designed API can be underused, misused and even not used. It can be annoying and even dangerous for both consumer and provider.

This is terrible! Poorly-designed APIs are terrifying and there are potentially millions of them. What can be done to avoid such a doomed fate? It’s dead simple: learn how to design APIs properly.

Learning API design

OK, APIs are programming web interfaces for software and developers; and there are millions of them. They should designed like everyday interfaces. Flawed design can be a disaster, so tread carefully. You might be thinking something along the lines of: if there are so many bad APIs out there, designing them must be really complicated, right?

No. It’s not.

Designing APIs isn’t complicated once you know how to design APIs. The global challenge of API design is awareness of all of its aspects. And the first step of this challenge is to understand what learningAPI design means.

Learning API design solfeggio

Fashions come and go in software. There have been and will be many different ways of exposing data and capabilities through software. There have been and will be many different ways of doing APIs to enable software communication over a network. You may have heard about RPC, SOAP, REST, gRPC or GraphQL. These are different ways of doing APIs, some are architectural styles, others are protocols or query languages, but to make it simpler let’s call them API styles. Although these styles may rather be different, they all require the same basic knowledge to design APIs using them. Some people may reduce API design to designing a technical software interface using a specific API style without understanding the real purpose and needs of such a design activity. It’s like playing an instrument without knowing solfeggio.

I’m a lazy guitar player, I’ve some basic solfeggio knowledge but almost didn’t use it because I learned songs using their tablatures (or tabs) instead of sheet music.

Figure 4 Playing the guitar without solfeggio knowledge

On a tablature, there’s no clef, nor notes or chords. Six lines exist, each one representing a guitar’s string. Numbers on these lines indicate where to put your fingers on the guitar’s fretboard. I mostly didn’t know which chords and note I was playing but I could play almost any song … if I had its tablature. But I can’t do anything else like composition or improvisation. And I also can’t play another instrument like the piano, for example. A friend of mine is a music teacher, as long as he understands how to do notes and chords, he can play any musical instrument to play any song, improvise and even compose music. He can do that because he has mastered music basic knowledge: solfeggio. He knows notes, chords, harmony, scales and how to combine them to create music that makes sense and does not make your ears bleed,on just about any musical instrument.

Jumping headfirst into programming interface design using a specific API style or reducing API design to the creation of some “functions” that can be called remotely without any other consideration is like playing the guitar using tablatures. You might be able to achieve the design of some decent APIs in the long run… after a few failures, failures that you could have avoided if you had first mastered API design solfeggio.

NOTE

Keep this in mind!

Many different ways of doing APIs exist, but they all require the same basic knowledge.

But, learning API solfeggio alone can be incredibly boring and even counter-productive without practicing. We need an instrument! I recommend starting with the REST API style.

Some basic knowledge is needed to know to master API design. But what are the equivalent of solfeggio, notes, clef, scales and chords in the API design world? What do we need to know to survive to API design and create brilliant APIs?

Mastering all aspects of API design

To survive and thrive in the world of API design, we need to have a keen eye and ask questions. Thousands of them. What happens if we don’t do that? What happens if we rush headfirst into the design of a programming interface neglecting others aspects of API design?

Figure 5. A complex API design use case

Such mistakes may lead to incomplete, user unfriendly, and even dangerous API design. Many things should be considered when designing an API. Designing the programming interface is one of them but there are others. Who are the users? Who owns the data? What flow and information are needed to achieve a specific action? Do we need to evolve existing operations? How does the underlying system provide the API? Are there security issues to be aware of? Sensitive data? And so on.Many questions and many aspects. But they can be grouped into five categories.

Figure 6. The API design diamond

These five categories are:goals, usable, programmable, constraints and evolvable. They form the API design diamond. Designing an API is, first and foremost, designing something which has goals. An API allows some people to do things that make sense for them. These identified goals can then be represented as a programmable interface. But, if nobody can understand what is to be achieved with this API and how to use it, what’s the point of creating it? An interface must be usable by both the people and the software that are intended to use it. Put simply, prioritising a User-Friendly Interface Design has to come first. For example, an interface for fleet management software should be easy for those with a knowledge of trucking to use. Moreover, an API has also to observe some constraints. An API exists in an environment. It’s an interface between two worlds which must be secured by design. It must take into account how it’s consumed (used) and implemented (how the system providing the API is built). And finally, an API evolves. An API’s evolution can be taken care of by wisely creating it and cautiously modifying it after that.

NOTE

Keep this in mind!

An API is a programmable representation of goals that that may evolve after its creation. Both goals and programmable representation must be easily understandable and usable and must also conform to constraints imposed by the environment in which the API is built and used.

If you’re aware of all the API design diamond’s facets and know how to deal with them then you’re ready to face any API design challenge. You’ll be able to shape brilliant and shiny APIs.

What we’ve learned

In this article we’ve investigated what these API things are and we’ve scratched the surface of what it really means to design them. We’ve discovered that an API is more than a simple Application Programming Interface and that their design is far more than defining some functions that can be remotely called by a software:

  • APIs we’re talking about in this article are web interfaces that allow software to interact with each other over a network to exchange data or trigger actions. Because of this they’re a pillar of our connected world.
  • APIs are interfaces for developers and their design is closer to user interface design than programming
  • API design is composed of many aspects and programming is only one of them
  • These fundamental aspects can be applied to the design of any style of API

That’s all for now.

If you want to learn more about how to design APIs that developers and software will love to use, check the book out on liveBook here and see this slide deck.