Building Better APIs Through Human-Centered Design

You are supported by thousands of application programming interfaces (APIs) every day of your life. When you pay for your coffee in the morning, APIs read your credit card, validate your balance, debit your account, and credit your barista. 

When you email a teammate during the day, they check your identity, route your thoughts across the world, and notify the recipient. When you read the news at night, they detect your curiosity, alert the media, and retrieve content. 

APIs are specifications for exactly how a machine communicates with everything outside of itself. They are designed to ease communication inside and between machines by defining how they speak, how they listen, and the context in which they do it. When they work properly, APIs are an unseen web of support for your life. 

And yet, despite the fact that end users like you don’t even see APIs, we believe they should be designed with a human-centered approach. Doing so will save time and frustration for developers, which results in a better product. Before we can design better APIs, however, we should first understand how they work and interact with the world around them. 

How APIs Work

The most common situation where customers will encounter APIs in U.Group products is in HTTP-based APIs. These APIs power websites and web applications. They enable applications to talk to the servers and databases that fill them with possibility and data. They typically specify two modes of system/user interaction:  

  1. Requests: a user interacts with a web application, which then communicates a desire for data or action from its supporting system or database 
  2. Responses: the system responds with some acknowledgement or information 

Requests may look like this: 

{ 

"name_to_search": "U.Group" 

} 

Responses may look like this: 

{ 

"name": "U.Group", 

"description": "U.Group is digital transformation partner helping organizations use technology and human-centered design to solve complex problems and create new opportunities." 

} 

These requests and responses happen below users’ level of usual interaction with the system. From their perspective, they type in a company’s name in a search box and get back a page of results about it. 

From a developer’s perspective, they can reference the API’s documentation while building the application. They can build their application against the specification that they will always get descriptions of a company if they request a valid company name in the “name_to_search” field. 

How Humans Interact with APIs 

No matter the level of interaction with APIs—from users indirectly relying on APIs running beneath an interface to the developers directly interacting with the code—both groups of people have different needs and expectations that need to be met. 

Users shouldn’t have to think about APIs at all—for them, APIs should be invisible, fast, dependable, and powerful enough to carry out the user’s intentions. The developers who do interact directly with APIs need them to be transparent, intuitive, well-documented, and powerful enough to bridge the gulf between human thought and computation.  

Since human interaction lies at the center of API programming and execution, it only makes sense to design them in a way that takes these users’ needs into account. Doing so allows APIs to reach their full potential and deliver the most value.  

APIs and the Eight Properties of Good Design 

At U.Group, we approach the API development process through the lens of tried and true design principles. These principles not only allow us to build APIs that are easy for developers to work with. They also ensure that our products are usable, inclusive, and driven by measurable value. 

We have identified eight principles that we believe that are fundamental and universal principles of good design. The unifying characteristic of these principles is that they make products easier to use—more powerful, more intuitive, more direct, and more transparent. Although these principles are applicable across many of the more traditional domains—advertising, applications, marketing literature, etc.—they also work for other fields too, like data science and APIs. 

At a minimum, U.Group has determined that good design should include these properties: 

  1. Unobtrusive: the product should not interfere with the service it provides. Users should spend as little time thinking about the means of delivery as possible. The product isn’t the point; the service and the customer are the point. 
  2. Discoverable: the product should be understood by its users. It should be natural and intuitive, self-documenting to the maximum extent possible, and supported completely by external documentation (in that order). 
  3. Responsive: the product should respond to users in natural, predictable, consistent ways. For example, if users want to filter, expand, or transform responses, the product should allow that.  
  4. Forgiving: the product should not allow users to act in a way that is against their own self-interest. If users make a mistake or query bad data, they should be allowed to resubmit corrected queries immediately without negative consequences. 
  5. Modeled: the product should represent its data self-consistently, transparently, helpfully, completely, and truthfully. 
  6. Long-lasting: the product should be reliable and durable. Customers should be able to build systems on top of it with confidence. Failing indefinite support, its lifespan should be explicitly documented within the system itself.
  7. Mapped: the product should be fully described by its documentation where it isn’t naturally discoverable. 
  8. Constrained: the product should allow users to interact with the system only in ways that are plausible, useful, and reasonable. Users must not be able to interact with the system in ways that will cause fundamental, unintending errors. They must always get an answer that has some value. 

By applying these fundamentals to APIs, you will ensure the inputs and outputs of a product meet the human needs of the people who use them. After all, the visual design of the user interface will only be as effective as the design of the underlying API itself. 

Stay tuned for more on human-centered API design in part two of this series. Want more on programming and UX best practices in the meantime? Register for our monthly newsletter.

Get alerted to new job postings, events, and insights by registering for our monthly newsletter.