Hierarchy of API Design Principle

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…