Designing for humans: better practices for creating user-centric API experiences


In a recent Postman Intergalactic session with the API Handyman, Arnaud Lauret, we discussed the importance of designing good API experiences. Designing good API experiences is essential for any business that wants to stay competitive in today’s digital world. APIs are the backbone of modern web and mobile applications because they allow developers to access data from other services and build powerful integrations with minimal effort.

For public, private, and partner APIs, the impact of the “good API experience” can lead to:

  • More usability and reusability
  • Less time to deliver higher value
  • APIs that evolve smoothly
  • Less risk of introducing breaking changes

The impact of the “bad API experience” can lead to:

  • High costs
  • Decreased productivity for both consumer and producer
  • Longer time for integration
  • Shift in delivery dates

Coffee talk: example scenario

Arnaud and I collaborated to come up with a Coffee Brewing API to demonstrate ideal API designs.

  • Use case (what): Get a coffee
  • Steps (how): Choose coffee beans and then brew coffee

In this example, we wanted to create some APIs for the use case of getting a coffee which could be broken down into two steps.

  1. Choosing a coffee bean
  2. Brewing a coffee

This example specifically has a GET request that provides a list of beans being used for coffee, and a POST request to prepare the coffee.

If you are interested in learning more about this Coffee Brewing API, go ahead and check out its definitions and fork the sample collection to test it out here.

While using this example as a guide, here are four aspects to keep in mind when designing APIs.

1. Naming

When it comes down to user-friendliness, consistent naming conventions can make your API easy to use and understand.

The rule of thumb when it comes to naming is that it should be consistent at every level. This includes endpoint names, method names, and response codes. We want to allow people to guess how APIs work. In our example, we use a GET request called /beans/ that provides a list of all bean elements, and to use /beans/{beanId}/ for a singular element. The better practice key here is to not mix up singular and plural—for example (like GET /beans + GET /bean/{beanId}), which can introduce complexity or inconsistency. Check out this blog post to learn more:

  • Check out this video highlight to see this in action:

2. Data types

APIs use data types to define the structure of data that is being sent or received by the system. Without proper data typing, there could be errors or misinterpretation of data, resulting in incorrect output or unintended consequences.

In our GET/beans/ example we designed a property called price to share the price of various beans. We designed this property to return two different data types:

  1. Number: to return amount
  2. Currency: to return ISO currency values

  • Check out this video highlight to see this in action:
It was important to our design to use multiple data types in our price object to specify the returned value. Getting specific with data types allows developers to write more efficient and maintainable code, as they provide a clear and concise way to describe the data that is being processed.

By using the appropriate data types, developers can improve the performance, reliability, and security of their APIs, which ultimately leads to a better user experience.

3. Required or not required

The use of “required” and “not required” parameters in APIs is critical for creating a consistent and predictable user experience. Required parameters are those that must be included in an API request to receive a valid response. They are essential for ensuring that the API can process the request and provide accurate data. Not-required parameters, on the other hand, are optional and are not necessary for the API to function correctly. They can provide additional information that may enhance the response or help to customize the output.

The best practice here is to require as little information as possible from the user, which allows users to perform an operation faster, thus reducing time to first call and increasing time to value.

In our POST /brewings example, we ask the user to require just the bean type which they can GET/beans/ endpoint. They roast type and the milk type are both not required and have default values associated with them. Therefore the user can send the API without clarifying roast, and milk type and still have a successful request returned.

This drastically reduces the time to the first call, as the user can send the API with the least amount of information and still get a successful request.

Overall, by properly defining the required and not required parameters in an API, developers can create clear expectations for users and reduce errors or confusion.

  • Check out this video highlight to see this in action:

4. Error handling

One of the most important and often overlooked aspects to consider is error handling.

Proper error handling is crucial for API design as it ensures that the API is reliable and can handle errors gracefully. When designing an API, it is important to consider all possible error scenarios and provide appropriate error messages that help developers understand and resolve the issue.

Let’s take a look at this in action with our POST /brewings API.

1. Error code provided but no data in request body

In this first scenario, we provide the 400 error code, but no data is returned to the user. Consequently, the user has no way of knowing what caused the error.

2. Error code provided and minimal data returned in request body

In this second scenario, we provide information about what the error is. However, it is still not the best practice, as we still do not provide a comprehensive view of the error and a way for the user to fix it.

3. Complete data provided with detailed error messages and possible fixes along with error code

This final scenario is the best practice for handling an error. We provide the error code and also return a lot of information in the JSON request, as well as instructions on how the user can troubleshoot and fix the error. We also provide meaningful feedback to the user by telling them exactly what data they need to provide in order to get a successful result.

Ultimately, a well-designed error-handling system helps to improve the user experience by providing meaningful feedback to users when something goes wrong. The key here is to provide the user with as much information as possible so that they can not only identify the error but also troubleshoot and fix it.

Without proper error handling, APIs can be vulnerable to security risks, performance issues, and user frustration. Therefore, effective error handling is a critical aspect of API design that should not be overlooked.

Watch the full Intergalactic Session

This blog post has provided an overview of topics such as naming, data types, required/non-required properties, and error handling. If you are interested in learning more, you can watch the full livestream video:

Learn more

Check out these additional resources to learn more about API design with Postman:

What do you think about this topic? Tell us in a comment below.


Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.