Any API needs to fulfill its responsibilities, such as gathering, structuring, delivering and securing data. But this is not enough to make the API really desirable for API consumers. What are the desirable properties of APIs?
Desirability can be regarded from the perspective of the consumer or from the perspective of the provider. Ideally, the API exposes properties that satisfy both perspectives.
In the following, we list a number of such desirable properties.
Consumer-Centric: The API is made for API consumers, not for the API provider. Regarding the input and output of the API, the perspective of the API consumer is relevant, not the perspective of the existing backend systems. The API needs to mediate between the nice, clean, simple format presented to the consumer and the complicated format used towards the backend system. The value of an API is in removing the complexity for the API consumers, but still, be valuable and relevant for the API consumer.
Simple: There should be a low barrier of entry for new API consumers. The API should be simple, so new users can get started quickly and easily. The API should be easy to learn and easy to use. The challenge is to create an API that not only looks much simpler but actually is much easier to use.
Self-Explanatory, Intuitive and Predictable: The URI needs to be predictable, the parameters need to be self-explanatory and the data objects need to be easy to understand. The API is consistent with the other APIs in the portfolio.
Explorable and Discoverable: An API can be explorable by API consumers. A curious API consumer can explore the API without reading the documentation. APIs should also be discoverable by machines. This requires enough machine-readable information in the API and following some conventions.
Well-Documented: Some consumers prefer reading documentation of the API. For these consumers the API needs to be documented in an easily digestible form, that is fun and exciting, too.
Atomic: The API operates only on one object and does only one thing — from the API consumer’s perspective. The fact that there are several steps involved on the side of the API provider is irrelevant in this context.
Forgiving: The API should deliver error messages that can be understood by the consumer. If the consumer made a mistake, the API provides hints for fixing the mistakes.
Secure and Compliant: The API needs to ensure that it can only be accessed by authenticated and authorized consumers. The API does not leak internal information. The API is compliant with best practices and security regulations.
Performant, Scalable and Available: For API consumers the performance of the API is an important requirement. A highly performant API allows them to build responsive apps with a great end-user experience. Successful APIs become more popular over time. The API and the underlying platform need to be scalable.
Interoperable and Standard-Conform: The API should apply relevant standards and follow industry conventions. Following conventions and standards also improves the understandability of the solution. The APIs should hide any implementation details.
Reusable: The API should not be specific for one API consumer or one project. The API itself should be reusable, but it should also be built from reusable components. This makes APIs consistent. The reusability property is desirable for the API provider, the resulting consistency among the API portfolio is desirable for the API consumer.
Backward-Compatible: An API needs to be backward compatible. Old clients need to be supported. If new features do not allow for backward compatibility, a new API or a new API version is created. Once APIs are published and used, they cannot be changed or taken away. Consumers rely on the APIs to work and to work in exactly the described manner. Even though APIs can be very well developed in an agile way, once they are published and used, all the agility has to be left behind and the given version of the API becomes immutable.
How do we use this long list of desirable API properties?
We can use it for evaluating the architecture of APIs or we can use it to figure out what we need to improve about the architecture, so it exhibits more desirable properties.
Also published on Medium.
