Designing APIs for Humans

One of the most discussed topics at this year’s NordicAPIs Platform Summit was API Design and how it can affect the way APIs are consumed. The discussions focussed on how design might affect the end users’ perception of your product. A number of speakers considered this a very important topic, and several discussions occurred throughout the event. According to Jason Harmon, Head of API Design at PayPal, “APIs are starting to look more like the product and less like the technology.” In other words, API Design is starting to look more and more like User Experience (UX), and less like a simple technical mapping of your app’s database.

Honza Javorek, from Apiary, clearly stated during his talk that “developers don’t really relate with the database style API design approach.” APIs should be seen as a way to provide functionality to the end user; they should follow the same usability rules defined by Peter Morville, best known as the UX Honeycomb:

Lessons from UX

In order to design an API using this new approach, you must first answer these seven questions:

Useful: Is the API useful from an end user point of view?
Usable: Can the API be quickly used by a developer and provide easy-to-use functionality?
Desirable: Is the API and the functionality it provides something that generates desire in developers and end users?
Findable: Can the API documentation be found easily, and can developers start using it immediately?
Accessible: Can the API provide functionality that makes third-party apps accessible to people with disabilities?
Credible: Is the data provided by the API trustworthy?
Valuable: Does the API contribute to the company’s bottom line and improve customer satisfaction?

Ronnie Mitra, from CA Technologies, first presented this correlation with the UX Honeycomb. He specified that “in the API space we build something on a machine for a machine to use, and this is wrong because there are people on the other side of API clients.”

Ronnie Mitra during his presentation at the platform summit

Mitra believes that what is missing is a process of API design similar to the one UX designers employs. We should follow what UX has been doing because APIs clearly impact how end users experience the product. UX experts usually follow an iterative process involving initial user research, where they understand how users will perceive the app. This step is so important that the Nielsen Norman Group, renowned in the UX industry, considers that there’s no UX without it.[well xclass=”text-center”]”API design decisions actually impact the end user experience, not just how developers are consuming it.” — Ronnie Mitra, CA Technologies
[easy-share buttons=”twitter,facebook,linkedin,google” counters=0 native=”no” url=”https://nordicapis.com/?p=2745″ text=”API design decisions actually impact the end user experience, not just how developers are consuming it – @mitraman of @CAinc”][/well]

The second step is related to ideation, or how to generate a lot of different ideas in a short amount of time. The belief is that the more ideas you have the more creative you are, and this in turn leads to a better design. Finally, the last step of the iteration is testing and validation. This can be done using manual or automated processes. These can range from simple user interviews to fully automated A/B tests that reveal which API features are used, and how frequently.

According to Mitra, you should focus on the ideation part of the process, and sketch as many API scenarios as possible. Coming up with different sketches helps you better understand what your API is about, and how it will finally be consumed. Sketching involves defining the supported API resources, their vocabulary, and which operations will manipulate those resources.

Sketches are the first step of a process that Mitra believes will be commonplace in the initial design phase of API products. You start by generating as many sketches as possible in order to provide a low-fidelity prototype. This first prototype can then be used by developers to test how the API responds to their requests. API Blueprint, for instance, lets you quickly generate mockups that can be tested against any existing client specification; similarly, you can create virtual APIs using SmartBear’s Ready! API. This increasingly important initial step, is only the first first in the process of delivering what a client needs. Next, you should deliver a second, high-fidelity Proof of Concept (PoC). This can be done by launching a pilot inside the company (if your API is an internal one), or within a preselected number of users (if the API is public). With other technologies such as Swagger or RAML, you can achieve similar results.

What Consumers Want

At the end of this process, you should have an API that is focused on what developers and end users need. Including this process helps you create an API that not only looks much simpler, but is much easier to use. APIs should not look complicated because, according to Johannes Lundberg from 46Elks, “the real value is on removing the complexity for your API consumers.”

Lundberg believes that API features are ‘sticky.’ This means that you shouldn’t remove them at some point in the future. Removing or changing a feature might break any existing client’s implementations, and that must be avoided. Harmon adds that thinking about how different APIs connect with each other is more important than defining a single API specification. System thinking is needed rather than a one-off thought process.

A possible way of closing this gap between what the API delivers and what consumers really want is to adhere to the HATEOAS design more strictly. HATEOAS, or Hypermedia as the Engine of Application State, says that consumers interact with APIs entirely through hypermedia, which providers generate dynamically. By employing hypermedia techniques, providers can offer hints on how to use the API by inspecting the responses themselves, making clients more adaptable to any particular change. Although this strategy frees providers from having to deliver and maintain high-quality documentation, it pushes the responsibility of understanding the API to client implementations.

Several speakers mentioned HATEOS and how it might help the API industry evolve into a more consumer-oriented space. Jakob Mattsson, from FishBrain, believes that “a consumer should interact with the application through the hyperlinks provided in the responses” and that “it shouldn’t require prior knowledge to navigate the API response structure.” While we’re still far from this reality, Mattsson suggests three rules that you should follow if you want to transition quickly:

No fixation: You should not use fixed resource names or hierarchies.
No types: You should use standardized media types and relation names, not the ones you create.
No prior knowledge: You should use a single entry point, where the state is driven by client selection on server-provided options.

The use of standardized media types is probably the most important of these rules. According to Irakli Nadareishvili from CA Technologies, “the key is the media type.” Nadareishvili believes that standard media types are what clients will use to understand what the API is about, and what is the expected response format. Clients will obtain that information from media types and adjust accordingly. Familiarity is very important, and that can only be obtained with a set of standardized media types that both providers and consumers understand.

While the future looks bright, we are still a long way from our goal. Pau Ramon from Redbooth believes that HATEOS will not be broadly used anytime soon. Ramon’s advice for now is to “bet on flat APIs” that provide responses with the requested data and nothing more. Harmon is not so radical — and his advice is to “be smart about the size of resources because there’s no perfect answer to this.”

Conclusion

Designing APIs for Humans shouldn’t be overly complicated, but it should be done following some proven process. The Nordic APIs Platform Summit provided evidence of a consensus confirming that API practitioners should follow the same procedures UX experts have been using for decades. In the end, APIs are going to be consumed by real people. Therefore, it follows that UX principles should be applied.

On the technical side, things are still unclear as to which standards and paradigms should be followed and when. On one side are the HATEOAS and Hypermedia followers who want to push the standardization of APIs that can be fully consumed without any human intervention. On the other side are the majority of API practitioners, who believe that the current standards will live for a long time — and are sure there is no easy way to implement a ‘one-size-fits-all’ API.

Wherever you stand on this controversy, one thing is clear: APIs affect your business’ bottom line and the way your product is perceived by real customers. This makes it imperative that you pay attention to API design, and follow the UX principles outlined above.

Do you have a different opinion? What’s your thought on this? Leave a comment here or get in touch to discuss this more!