Episode 86

When it comes to creating a piece of software, we need to ask ourselves three important questions. Why are we doing this? What are we doing? How are we going to do that? Software developers tend to focus on the last one, since technology seems to be their domain. However, the question that should be considered first is why, as Simon Senek pointed out in his book. Let’s explore those three question in the context of designing web APIs.

In the second part of the article, we will take closer look at the “how” part from the user experience design point of view. The user will be a software developer consuming our API in this case.

Why?

For money, of course. Traditionally web applications earned money by serving their users data and functionality via some kind of front-end. The front-end was talking to the back-end and back-end was talking to the database. In order to satisfy growing needs, enrich user experience, and avoid reinventing the wheel, applications started to talk to other applications and use their data and functionality over the network. As the business was growing, we came into possession of more and more of valuable data and functionalities, so why not to make money on that too? To be able to deliver that value, we need…

What?

… server-side web API. The gateway that allows other applications to use our system in secure and controlled manner. The web API is a collection of publicly available endpoints that accepts request and returns responses with well-defined structure. Traditionally, a part of larger application, nowadays often a separate micro-service that focuses on translating external requests to internal formats, managing traffic and protecting core back-end components. We know what to build now, but how to do that well?

How?

That will be the objective of this article, and few further ones, as the topic is vastly broad. Today we are going to focus on high-level overview of the matter. Key observation here is that web API is for developers as GUI is for regular users. Although web API facilitates machine-to-machine communication, those machines are programmed by humans, and those humans should be taken care of. In other words, developers of applications that consumes our API are our users. A lot of effort was made to study how to build effective graphical user interfaces, and web APIs should be no exception. The core principles actually stays the same.

Peter Morville, in his article published in 2004, listed six facets of good user experience design that put together create value for the customer. Originating from generic human-computer interaction, they can be applied to developer-API interaction as well with a little creativity.

Useful

“As practitioners, we can’t be content to paint within the lines drawn by managers. We must have the courage and creativity to ask whether our products and systems are useful, and to apply our knowledge of craft + medium to define innovative solutions that are more useful.”

First reason to use an API is to get the job done. So there has to be a core business value in the form of being able to perform organized operations on data and making stuff happen. Besides that, there are many aspects that can help our users do their work. Some are more product-oriented, some are more technical. An example of the first one would be an alias for common collection queries. Instead of specifying type and time range in the ticket system, we could add something like ?page=recentlyClosed  to the collection URL to get what we want. An example of something more technical would be adding ?prettyPrint=true which would add tabs and newlines to the object, so that it is readable directly in the browser and makes developer life easier when playing around with new API.

Usable

“Ease of use remains vital, and yet the interface-centered methods and perspectives of human-computer interaction do not address all dimensions of web design. In short, usability is necessary but not sufficient.”

There are two powerful qualities in people – intuition and laziness. Intuition equips us with expectations on how something will behave. A lot of this can be described with semantics of the HTTP protocol itself – methods, status codes and headers. Why not use it? Following the Principle Of Least Astonishment, the more we confront to standards, the less work our user will have to do to consume our API. If deleting cars uses HTTP DELETE method on the car resource, it’s more obvious than GET on deleteCar or removeCar endpoint. It lets our users be lazy in regard of comprehending our system, making it more usable in turn. Similar with standard status codes and headers.

Desirable

“Our quest for efficiency must be tempered by an appreciation for the power and value of image, identity, brand, and other elements of emotional design.”

People like to feel appreciated and being taken care of. It’s no different with software developers. If the API is important to the business, let’s put it close to the top level domain in the URL instead of burring it under pile of slashes and words like dev, rest or internal. Create a community portal with forum, tech blog and other useful stuff. When returning error responses, provide a link to appropriate chapter of documentation or FAQ. Devs will love such product.

Findable

“We must strive to design navigable web sites and locatable objects, so users can find what they need.”

First condition to use an API is being able to locate it. Similarly with the API documentation. Documentation is the face of our product, so why hide it behind authentication and necessity to write to support in order to get credentials? Make it public. Sure, it’s a security risk, but if someone really wants to DDOs you, he/she will find  it anyway. On the technical side – let the API describe itself by following HATEOAS principle and including in responses links to possible operations related to the resource.

Accessible

“Just as our buildings have elevators and ramps, our web sites should be accessible to people with disabilities (more than 10% of the population). Today, it’s good business and the ethical thing to do. Eventually, it will become the law.”

Disabilities might be considered in the technical sense. For example, if someone sits behind a proxy that only passes GET and POST requests, it would be helpful to allow HTTP method overriding via X-HTTP-Method-Override header or query parameter. Another example would be to make a nod towards clients with very limited bandwidth by providing an option to return subsets of objects or to compress responses on demand.

Credible

“Thanks to the Web Credibility Project, we’re beginning to understand the design elements that influence whether users trust and believe what we tell them.”

Credibility has many faces. It might be solid security mechanisms to protect both our back-end and the data that the client entrust us. It might be an ability to scale and handle traffic spikes. It might be nearly 100% uptime. Many of those are infrastructural concerns beyond the topic of web API design, however one of the faces I would suggest to incorporate into the design is transparency. If we screw things over, let’s be clear about that. For example, if the server can’t serve more request, use the X-Rate-Limit-* family of headers and HTTP 429 Too Many Request status instead of just return useless HTTP 500 status.

What’s next?

It’s difficult to fulfill all six points. The sweet spot depends on our context, users, business, resources and many different things. My metaphor between designing for common users and API consumers might seem a bit philosophical and sketchy but I think it will be a good starting point to the series of detailed articles on the art of web API design I’m planning to write. As usual, it started with idea for one, with a simple list of tips, as an addition to the talk I was recently preparing for Software Talks in Wrocław. As it turned out, I gathered quite a lot of material for that and made over 25 pages of notes alongside (and growing), so I’ve decided it would be a waste not to share it with you in proper form. Stay tuned for more content.

By the way, if you happen to be in Wrocław in January, I will be talking about API design at the upcoming Wrocław Java User Group meetup which you are welcome to attend to. I’ve also added a Talks page to the blog, to list my speaking activities.

Image sources:

• ICAM 381
• artificialdesign
• skareo