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.
- Choosing a coffee bean
- 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:
- Number: to return amount
- Currency: to return ISO currency values
- Check out this video highlight to see this in action:
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.