The pure implementation of an API is almost straightforward, if not simple. In contrast, API design is not straightforward. Why? Because API design involves many aspects and constraints such as architectural styles (e.g., REST), API governance, backend capabilities, performance, user experience, value proposition, you name it. In other words, there are many constraints and even trade-offs to take into consideration.
Consequently, in our daily work we typically end up in unsatisfying, endless discussions about what should be right and what wrong, how to interpret the Web standards, what are other API providers doing, etc.
API design is the creation of the best API solution under the constraints of value proposition, user experience and API interface design.
In all our API design discussions, however, we typically miss two fundamental aspects: create value for the customer and provide a good user experience. We realized that no customer cares about a good RESTful API interface. No customer cares about simple developer onboarding, good API documentation or an API playground or sandbox. But customers care about resolving their problems and getting their job done. Afterwards, they care user experience and finally well designed interfaces.
API design is the process of finding the best solution under the constraints of value proposition, user experience and API interface design. For that reason, we invented the Hierarchy of API Design Principles, analogously to Maslov’s hierarchy of needs, which guides our API design from the very basics to the art of API interface design.
The following figure presents the Hierarchy of API Design Principles. The foundation of a valuable API is provide relevant and viable value to the customer. Your job as an API Product Manager is to find and define a relevant value proposition and validate it with the customer.
Based on the value proposition, provide a good user experience to the user or rather developer. Provide users frictionless onboarding, useful API documentation and tutorials, sandbox to test and integrate your APIs. And think how your API can best help the user getting the job done. Extend your API management platform to provide a great user experience.
Finally, design the technical API interface under the constraints of value proposition and user experience. Apply you API governance, design guidelines, and your engineer’s wisdom and experience. This is what we call the API interface philosophy.
We are using the Hierarchy of API Design Principles frequently because it helps us to keep the most important aspect in focus: the creation of value for our customers. Remember that your value proposition and user experience are not negotiable. Adapt your API interface philosophy if needed.
Deliver Value to the Customer
Your primary goal is to provide value to the API consumer, help the customer to get his job done! Hence, the value proposition, as part of the API product, is the single non-negotiable aspect. The value proposition sets the context and constraints to define the user experience and to define the API interface.
Our Value Proposition Interface Canvas is a method to make the value proposition explicit and how your customers can exploit it via an API. The Value Proposition Interface Canvas guides you trough the process of identifying customer’s pains & gains getting his job done, making your value proposition explicit by means of pain relievers and gain creators, and how your API provides an interface to exploit your value proposition.
You can find an example in our article “Paradigm Shift: From API to VPI“. In short, in our referenced example we use the value proposition of verifying identities to guide the design of the user experience and of the API interface. As a result, we ended up with the Identity Verification API and the corresponding resources.
One of the most important challenges is to consistently engage your teams to understand why they do what they do. For that reason, we introduced The Daily Pitch. Everybody, engineers in particular, have to pitch an API product to the rest of the internal team. As a result, they understand why they do what they do, are more motivated and passionate, make better decisions independently, and add insights to improve the product.
Provide Good User Experience to the Customer
Good APIs are like love at first sight. Either you love them immediately or you don’t care much. The user experience is how the value can be captured by the API consumer. Good user experience of APIs involves the following aspects:
Simplicity (Flexibility-Usability Trade-off): How simple is it for a customer to get the job done? How complex will API usage patterns be?
Self-Explanatory: Does the customer easily understand how to use the API to get his job done?
Consistency: Is the user experience and the behaviour of the API consistent and is it consistent with other APIs (i.e., API governance)?
Forgiveness: Does the API forgive customer errors or ambiguities?
Standards: Do we apply useful standards?
Human-Centered API Design
APIs are used in machine-to-machine communication. But this doesn’t mean that we can create a cryptic and complicated design API interface. Because ultimately, a human developer has to understand it and use it.
In the following, we present two examples of different SMS APIs to send a short text message to a phone. The first one corresponds to the GSMA standard, the second corresponds to the result of human-centered API design. Which one is easy to understand and is less effort to use?
SMS API according to GSMA standard:
{
{
"outboundSMSMessageRequest": {
"address": ["tel:+41435551212"],
"clientCorrelator": "10002",
"outboundSMSTextMessage": {
"message": "Test SMS from 7511"
},
"senderAddress": "tel:7511",
"senderName": "Super Send"
}
}
}SMS API based on Human-Centered Design:
{
"from": "7511",
"to": "+41435551212",
"message": "Test SMS from 7511"
}Both SMS API examples do send a text message to a phone. As you have noticed, the human-centered SMS API, however, is much simpler if compared to the SMS API from the GSMA standard. This latter API is much more complex but might probably allow for multiple receivers (?).
When we design an API, we have to consider the trade-off between usability and flexibility. Specifically, we have to understand the job that customers want to get done. When we know the problem then we can easier determine the sweet spot between usability and flexibility. For that reason, it’s crucial to interact with customers and not just design APIs on a drawing board somewhere in the basement.
The following aspects are especially relevant to provide a good user experience:
Good API documentation with tutorials and how-tos.
API Sandbox to test APIs and learn their behaviour
Error handling with helpful error messages
Frictionless on-boarding
API Interface Design & Architecture (aka Philosophy)
There are many good readings and books about good API design and API architecture. Especially noteworthy is the book on RESTful API Design from our close colleague Matt Biehl:
Matthias Biehl: “RESTful API Design: Best Practices in API Design with REST”