API-First Design Approach

architecture

This item was not updated in last three versions of the Radar. Should it have appeared in one of the more recent editions, there is a good chance it remains pertinent. However, if the item dates back further, its relevance may have diminished and our current evaluation could vary. Regrettably, our capacity to consistently revisit items from past Radar editions is limited.

Mar 2022

Adopt

The API of any software we develop shapes in which way developers, teams, customers and users interact with our software.

No matter if a Frontend-API like GraphQL, a rpc-API like gRPC or an internal API published by a module in a larger project or shared library, messing the API up always creates headaches and is hard to correct. If we stick to semantic versioning, it's actually pretty impossible to change a once-published API without breaking consumers.

By today's standards we prioritize API design before actual development, to be clear on how our software interacts, and thus move this pattern to "adopt".

Mar 2017

Trial

The API-First Design Approach puts the API design at the beginning of the implementation without any constraints, for example, from the current IT infrastructure or the implementation itself. The idea is to design the API in a way that it serves its purpose best and the consumers are enabled to work efficiently.

There are several advantages to this approach. For example, it can help to avoid reflecting the internal structure of the application or any internal constraints. Furthermore, as one of the most important design aspects is consistency, one can define features such as the behavior of security, URL schemes, and API keys upfront. It also helps speed up parallel implementation. A team that consumes the API can start working directly after the API design because it can easily be mocked.

There are several tools for modelling an API, but here at DCX we mainly use RAML as it provides a rich set of tools for generating documentation, mocking and more. For mocking we use WireMock, for example.

Related to the "API-First" approach is the "Headless" approach where an existing application (with or without existing API) is used as a backend for a separate frontend. We used this with sucess for Magento-based E-Commerce platforms. This allows encapsulating the core features of that application, while integrating it into a larger landscape of components using its API as a unified way to interact between components. Decoupling the core logic from its presentation layer allows picking the best technology stack for the various parts independently.

For further reading see: