In recent years, software development has constantly been changing, just like the focus does when starting a new project. Nowadays, a new software project’s focus should be on the software’s APIs, which requires the developers and architects to rethink their perspectives. It has distinct advantages and makes work contributions easier.

Now, the focus is on the API

The purpose of building software is to process data. Data flows into systems or must be made available to others. This is why we need APIs. Since they are the backbone of the API-first approach’s core, the focus is on the API from the beginning.

In today’s approaches, we often think in microservices and headless backend systems, which pushed 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 API clients can start implementing when the API is defined. The same is true for the headless backends. Most of us want to consume a lot of data in our everyday lives, for instance, on the browser or mobile apps. In this case, a headless application provides an API, and then a mobile app or a JavaScript browser app can consume the same API.

When developing 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 does: creates a certain contract at the beginning of the project.

The API is Now a Product

Defining the API as a product implies the API is relevant for more than developers. Product managers and product owners need to be centrally involved in 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 payment service provider (PSP), the market is very competitive. Having a great product can give you an edge over 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 questions show that a good developer experience is an important criterion for a good API and that decisions are no longer only made on a management level but especially from the technical perspective.

API Definition and Documentation

Documentation is a task developers do not like very much, so you must keep the hurdles as low as possible. That way, you can ensure the documentation stays maintained and up to date.

OpenAPI specification was released recently; it is a helpful tool to define APIs at the first step of HTTP/RESTful APIs. The OpenAPI specification is easy to interpret by machines but can also be well maintained and serviced by humans after a short training period.

This format is understood by developers and other stakeholders such as product managers and product owners, since the format of an API is easy to understand. One of the reasons why the format is easy to understand is that OpenAPI is a common standard and, therefore, offers nice possibilities for visualization. In this context, Swagger UI is widely used (a brief example can be found here), but there are 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 implementation, you can build a well-designed API from the beginning that includes many use cases. In addition, it allows you to extend the API quickly and easily.

Defining an API in advance can take 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 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, and talking to stakeholders. It might take time to create API documentation that thinks through all use cases in detail and the ways a client will interact with the system.

The result is well-defined API documentation, so when the development process starts, there are unlikely to be more changes (except new features).

An API definition (however it may look) is a contract. A contract must be fulfilled with its implementation. This means that implementation can start on both sides of the API as soon as the definition is accepted. The API’s producer and consumers can work in parallel to implement this API, which makes it so 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 the 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 with as many stakeholders as possible. With a new feature or bug fix, there are probably not as many stakeholders involved as with new development, but that depends entirely on the use case.

• Assumption: We have two frontend applications that use the same backend. Once the API is aligned, the frontend teams can generate a mock and implement 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 can be released. A clearly defined, well-aligned API makes the implementation smoother and contributes to significantly higher software quality. This is an 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 other advantages. With OpenAPI, you automatically get mocks with examples added to the definition, simplifying API integration, 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 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 your API documentation becomes part of your development process. This generated code directly includes the validation defined in the OpenAPI. This increases the automation of the development process, which ensures the API documentation is always up to date.

API First Makes Everyone Happier

Is this true? Yes. According to the following statistics, about 80% of the respondents said API-first companies are more productive, create better software, and are happier. In addition, the API-first approach also seems to have advantages in other areas. For example, new products and features can be developed faster, and 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 mindset shift from the developers and rethinking the company. The API has to be seen as a product offering a range of advantages. However, is there anything wrong with thinking about your API from the start, even if the company is not yet ready? No, but it does not always have to be an explicit API definition if that would be inappropriate for a 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 need an API specification.

Even if you, as a developer, write a small script that only runs on your 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 a domain model is not an important part of the conception in the API-first approach.

Following the API first approach is hard, but it is worth the hard work in the end because you are building a better piece of software.

Tips and Tricks

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

Helpful tools
miro is a great tool when brainstorming, but many other tools are useful. Egon.io is an excellent tool for identifying use cases when domain storytelling.

To create OpenAPI documentation, you only need a text editor. Swagger-UI, which I’ve already mentioned, displays changes and errors directly, so 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 don’t have to context switch.

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

Detecting the right tool for mocks is a bit more difficult. It depends on what you want to use the mocks for. I often use wiremock, even if there is no OpenAPI support currently, and configure the mock as needed. Another tool is Prism, where you can get a mock directly based on the OpenAPI documentation.

But there are many more tools, so you must find the right one for your project. This is a sample of the tools I use.

OpenAPI Does Not Only Work With HTTP
So far, we have only discussed the HTTP/RESTful API. While this is what the OpenAPI specification was created for, you can also use an OpenAPI definition for other APIs, like message queues, to create a unified definition of the messages.

Does that make sense? In my eyes, definitely. Since you have a uniform format for your software’s API, you can also use a part of the code generation — the creation of the models.

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

But the same would apply to file import. In this case, you can also consider sticking to the XSD validation for XML files, for example, rather than implementing an OpenAPI validation.

Automation against manual errors
You should automate wherever possible to make your life easier. This also applies to APIs. APIs change. APIs must change and live, or they die 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. Often, these include an important part of APIs — the input validation. Although this is not always possible with an OpenAPI description (because dependencies between fields are hard to map), 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 and goes further into your API’s structure. There RFC 7807 is an interesting approach to defining error responses. The main advantage of using standards properly is that they are either already known or you can easily read them.

Thanks for reading.