API first - the new way of software development

In recent years there have been constant changes in the light of software development, just like the focus when starting a new project. Nowadays, the focus of a new software project should be on the APIs of the software. This requires a rethinking from the perspective of architects and developers, it has distinct advantages and makes work contributions easier.

The focus is on the API

Building software has the purpose of processing data - data flows into systems or must be made available to others. This is why we need APIs and this is at the core of the API first approach. The focus is on the API from the beginning.

In today’s approaches we often think in microservices and headless backend systems - two approaches that pushed the API first thinking. Microservices should be as independent as possible. Once an API is defined for the service, it does not matter how the service behind the API is developed. What matters is, that clients of the API can start implementing on their side when the API is defined. Same is true for the headless backends. Most of us want to consume a lot of data as well in our everyday live, for instance on the browser or on mobile apps. In this regard, a headless application just provides an API and then a mobile app or a JavaScript browser app can consume the same API.

In the development of a frontend application, developers usually use mockups from the UI and UX designer with exact specifications of what the frontend has to look like and which functionality is expected from the different buttons. This is exactly what an API definition is doing: a certain kind of contract is defined at the beginning of the project.

The API is now a product

Defining the API as a product implies that the API has not only relevance for developers. Product managers and product owners need to be centrally involved in the process of API definition. Especially if it is a public interface that should allow others to interact with the system.

For example from the perspective of a PSP (payment service provider) the market is very competitive. That means that having a great product can give you an edge over the competitors. One of the first things a potential customer is looking for is the API. Does this API fit into the business processes? Is it easy to understand and implement the API? Is the API well documented? Those kinds of questions underline that a good developer experience is an important criterion for a good API and decisions are no longer only made on a management level, but especially from the technical perspective.

API definition and documentation

Documentation is a task that developers do not like very much. That is why you must keep the hurdle for such documentation as low as possible. You need to ensure that it is maintained and always up to date.

For the definition of APIs (we are talking here in a first step about HTTP / RESTful APIs) the OpenAPI specification has emerged in recent years. The OpenAPI specification has the advantage that it is easy to interpret by machines but can also be well maintained and serviced by humans after a short training period.

This format is not only understood by developers, but as well by other stakeholder such as product managers / product owners since the format of an API is quite easy to understand. One of the reason why the format is easy to understand is that OpenAPI is a common standard and therefore offers nice possibilities of visualization. In this context Swagger UI is widely used (a brief example can be found here ) but there are also other tools. At Worldline we also use Redoc for API documentation (the same example with the Petstore here ).

When you use common standards and discuss the API with many stakeholders before the implementation, you can build a well designed API from the beginning that includes a high number of use cases. In addition, it ideally offers the possibility to extend the API quickly and easily.

Defining an API in advance can take some time, depending on its size and complexity. This is especially true if the API is discussed with as many stakeholders as possible. Depending on the time pressure, it can make sense to start developing the system during the API definition phase. In most cases the basics of the system can already be developed until you really get to the API.

Improving the development process

The API first approach has an impact on the development process. Instead of starting the development in the IDE, the API first approach starts with brainstorming, planning, talking to stakeholders. It might take some of time to create an API documentation and to think through all use cases in detail, how a client will interact with the system. The result is a well defined API documentation, so when the development process is starting, there are ideally no more changes (with the exception of new features).

An API definition (however it may look) is a contract. A contract that must be fulfilled with its implementation. This means that implementation can start directly on both sides of the API as soon as the definition is accepted. The producer and the consumers of the API can work in parallel to implement this API. So the different development teams are decoupled in their work.

To illustrate the API First approach, here is an example of how parallel working can work. In a first step, the API is designed or adapted. The approach works for new features and bug fixes as well as for new development.

• Plan the API together with as many stakeholders as possible.With a new feature or bug fix, there are probably not quite as many stakeholders involved as with new development, but that depends entirely on the use case.
• Assumption: We have 2 frontend applications that use the same backend. Once the API is aligned, the frontend teams can generate a mock and start implementing against it. In parallel, the backend team starts customizing the backend for the use case.

• Once all areas of development are complete, the integration can be tested and the new version of the software released.

An aligned and clearly defined API makes the implementation smoother and ultimately contributes to a significantly higher quality of the software. This is a very important factor as it pays off in terms of maintenance and maintainability. Moreover, this allows you to focus on the use cases and features during development.

An OpenAPI definition also has some other advantages. With OpenAPI you automatically get mocks with examples added to the definition, which clearly simplifies the integration of an API especially in the development phase. You still must test the integration of the two systems later, but you don’t have to build a suitable mock yourself for the development.

When using the OpenAPI definition to generate your code automatically, you will keep the API definition up to date all the time, meaning that the documentation of your API becomes part of your development process. This generated code directly includes the validation defined in the OpenAPI. With this point the automation of the development process is increased and we ensure that the API documentation is always up to date.

API first makes happy

Is this true? At least according to the following statistics, about 80% of the respondents said that API first companies are more productive, create better software and are happier. In addition, the API first approach also seems to have its advantages in other points. For example, new products and features can be developed faster or security risks can be eliminated faster.

Source: https://www.postman.com/state-of-api/api-first-strategies/#API-first-strategies

Conclusion

The first step requires a change of mind of the developers and a rethinking in the company. The API has to be seen as a product which offers a whole range of advantages. However, is there anything wrong with thinking about your API from the start, even if the company may not be ready yet? No, but it does not always have to be an explicit API definition if that would be inappropriate for certain use case. For example, if we write a CLI application that reads in a text file and outputs it to the CLI, then we do not really need an API specification.

Even if you as a developer write a small script that only runs on your own computer you do not have to think about the API. You use it yourself and can change it as you like. In these cases, the data model may be the focus of the conception. However, this does not mean that a domain model is not also an important part of the conception in API first approach.

To follow the API first approach is a hard way to go, but in the end it is worth the hard work, because you are building a better piece of software.

Tips & Tricks

Finally, I would like to share a few tips that have made my job a lot easier over the years.

Helpful Tools

For the brainstorming at the beginning of the project miro is a great tool, but here are as well many other tools useful for brainstorming. A tool for domain storytelling to identify the use cases is Egon.io .

To create an OpenAPI documentation you basically only need a text editor. Helpful here is the already mentioned tool Swagger-UI where the changes and errors are displayed directly and you can perform test requests. I use IntelliJ with the corresponding OpenAPI plugin to create the Api specification, so I stay in my IDE and have no context switch.

As a OpenAPI linter, I personally like vacuum . With vacuum you can simply pull the docker image and run the linter.

Detecting the right tool for mocks from the list of tools is a bit more difficult. It depends a bit on the use case and the use of the mocks. I often use wiremock , even if there is no OpenAPI support currently, but configure the mock as needed. Another tool would be Prism with which you can get a mock directly based on the OpenAPI documentation.

But there are many more tools in all areas where you have to find the right one for yourself. This is only a selection of tools I use.

OpenAPI does not only work with HTTP

So far, we have just been talking about the HTTP/RESTful API. This is exactly what the OpenAPI specification was created for. But you can also use an OpenAPI definition for other APIs like message queues to have a unified definition of the messages in such a queue. Does that make sense? In my eyes definitely since you have a uniform format for the APIs of your software. In this light you can also use a part of the code generation - the creation of the models.

Another tool is AsyncAPI . It is very similar to OpenAPI and is created for generating asynchronous API documentation. The current tooling includes support for common message brokers such as Apache Kafka and RabbitMQ and languages including Python, Java and Nodejs.

But the same would apply to file import. In this case you can also think about whether to stick to the XSD validation for XML files for example or whether to implement an OpenAPI validation.

Automation against manual errors

You should automate wherever it is possible to make your life as a developer easier. This also applies to APIs. APIs change. APIs must change and live or they are dead and unused. The more manual steps you have with an API change, the more errors can slip in.

Generating the client or server from the API specification is now possible for some programming languages. This also directly includes a very important part of APIs, the input validation. Although this is not always fully possible with an OpenAPI description (because dependencies between fields are hard to map) at least a solid basic validation is possible. For specific cases, however, validators have to be developed.

Using standards

One final recommendation to make your API more usable is to stick to certain standards. This starts with the HTTP methods and status codes, but also goes further into the structure of your API. There RFC 7807 is as an interesting approach to define error responses. The main advantage of using standards the way they are meant to be used is that they are either already known or you can easily read them.