The API-First principle and Design First vs. Code First

According to the API First Principle it is required that at the beginning of the development it is specified exactly which functionalities are to be made available externally. Above all, an API is developed that offers everything a developer needs. Based on this, the final product, i.e. the application, is then built.

The API is considered a first-class artifact. This approach also allows several teams to work together without influencing the other development process. Basically three principles apply here.

• First, the API is the first user interface of the application
• Second, the implementation follows only after the API. The implementation can change, but the API should be independent of it
• Third, the API must be described. From this it follows that it is easy to understand and simple to use. The best way to do this would be a so-called self-descriptive API

These points are explained as examples in the figure. On the left, the process is structured in such a way that a design is worked out first. Then the backend team works on a prototype while the frontend team waits. Once the prototype is ready, a documented API can be used. This is called synchronous development. If changes are necessary, the process has to be restarted.

On the right, the procedure according to the API-First principle is now shown. Parallel development is possible here. At the beginning Mock API`s are created. Now all teams, both front- and back-end, start with their developments. Once the API is completed, all teams can switch to the implemented API.

Design First vs. Code First

In connection with an API, there are still two approaches. These are Design First and Code First. In the Design First approach, a Swagger document is created first, from which the API is then created. This makes sense if the API has a very critical function or it is very important that communication about it works. It is also useful when planning is needed to manage large systems. For example, if a monolith is to be broken into microservice with different functionalities. Also some frameworks require the design decision first. With the Code First Approach the API is created by coding. Then the document is created from the code. This is useful for small independent APIs. Also when a fast development is necessary.