Designing APIs is very hard work

Welcome to a situation from the everyday life of a development team. It is Wednesday and the planning for the upcoming sprint is in full swing. The team is supposed to make estimations regarding a new API to be created for the ERP solution. For all members of the team the solution based on a rest(ful) API seems clear and is estimated to take a small amount of time. During the sprint, after an initial feedback loop with the consumer, it becomes clear that the use case of the interface is not so clear and unambiguous after all. Likewise, the concerns of security were also left out. So at the end of the sprint no API could be provided. Why could misinterpretations and misestimations occur?

Exactly this question is not so easy to answer. Because creating an API with a good experience is not that easy. But what exactly is not simple? As a rule, APIs are created for a specific purpose or known consumers. Mostly also still using the “code first” approach, i.e. the API is created directly when the code is written and then a description is created afterwards. When using code first, the consumers have no chance to test the interface sufficiently for its purpose based on its description. With “API first” now exactly this problem is tried to counteract. However, this can also lead to misinterpretations, since one simply creates an API if the use case and the consumers are not known beforehand. So it would probably be better to call the approach “API by use case first”. For this approach it is also important to get away from the backend of the service and its supposed structure. After all, a description according to the OpenAPI specification says nothing about the architecture of the downstream service that provides the data for the API. After the explanation of the use case, we would like to turn our attention once again to the API consumers. Here, as for a good user experience, the credo “you are not user” applies. Knowing the consumer or consumers of an API is the be-all and end-all here. It can pay off to work with personas in order to narrow down the circle of consumers accordingly. After all, a data scientist has different requirements for an API than an app developer. The team now knows the use case and the consumer(s) and could now start the initial design of the API. Why “could” you, as a reader, will now surely ask yourself. The team knows the business use case, but the provisioning of an API should also establish frameworks regarding the protocol. Is REST really expected on the consumer side or would something asynchronous fit better. Only when this has been sufficiently clarified does it make sense to start with the design.

To speed up consumer feedback, especially to eliminate misunderstandings, the API is made available with the help of a mock. This is especially important with regard to the data models that are made available via API. With regard to REST, the team can return a single resource or even a collection of resources (collections) via an endpoint of an API. It is also important to talk about the expected error responses of an API and to record this description. At this point, it also makes sense to include a standard such as Problem JSON in order to increase the experience with regard to the API with concrete error responses.

This shows that even simple API design challenges can be more complicated than they might seem at first glance. Besides design, there are many other interesting topics within the API worlds that I would like to share my thoughts on in the coming issues.