Design API First as a pattern for designing interservice contracts
Outside the window is 2023, and among developers there is only talk about microservices and API First. Despite the fact that these topics are not new, it seems that their relevance is even gaining momentum.
A lot has already been written about microservices, both theoretical and practical. This approach also has its evangelists (Microservice Architecture) 🙂 In general, this topic is quite holivar, especially at extreme points of view. Today we will postpone it, but we will definitely return in the context of the topic of this article. Of course, this will be a no less discussed story dedicated to the API First methodology and programming interfaces (first of all, the web, but not only) in the design and development of modern information systems 🙂
My name is Anton, I am the head of the Architectural Committee at SimbirSoft. We use the API First approach for projects of very different directions, where there are several development teams (at least Backend and Frontend), as well as with high uncertainty at the implementation stage (rapidly changing requirements and goals, parallel design and implementation processes, high demands on TTM, etc.) Further).
Since API First is not something new for many development teams, we decided not to write about what everyone already knows, but to focus on individual issues and understand the practical aspect of applying the API First methodology in terms of design, prototyping and development.
This material opens a series of articles devoted to the practical implementation of the API First methodology in the development of our teams. To be precise, we favor API First’s “little brother” practicing design – known as Design API First. To avoid confusion, hereinafter the term “API First” will refer to the approach to software development, and the terms “Design API First” and “Design First” will denote software design within the framework of the API First approach.
The article will be useful to all architects and developers who want to implement the API First approach on a project.
First, let’s get acquainted with the definition, consider the prerequisites and reasons for using the methodology, then analyze the goals and objectives. In conclusion, we will provide our conclusions, as well as errors, problems and pitfalls that we had to face.
Note that the main guideline in the work done for our team was precisely the design of the API and the ability to test its results before writing the code. Here are other important test points from our case study:
Reduced development costs and time to market.
Parallel development of the backend and frontend parts of the application.
The ability to make changes to the specification after the start of development (programming).
Creation of basic (reference) specifications for typical subject areas.
Possibility to create SDK for basic specifications in different programming languages.
API design by an architect and analyst, not by a developer, to reduce the risk and error rate of direct implementation (coding).
Modern software development standards impose high requirements that require an appropriate response from both individual development teams and leading companies in the domestic software industry.
Today’s trends are due not so much to the fashion for “micro” (microservices, microfrontendsmicroapis), how much the development of software development methodologies, the growth of teams, the complication of the software being developed and the increase in requirements for it.
In microservices more relevant than ever reactive programming manifest, namely, its interpretation: modern software must remain responsive and functional in the face of failures or software errors, as well as at times of peak loads on various parts of the system. Thus, microservice architectures are designed to solve the problems of calling the present, outlined above. But, as you know, the use of additional levels of abstraction in the design and development of software does not go unnoticed. There are costs involved in maintaining these levels. One of the side effects that needs attention is the need for more frequent and consistent interaction among participants and teams that work on different parts (microservices) of a software solution.
We will consider that the harbinger of the approach to solving this problem was the release of the Gartner article: “Welcome to the API Economy“. The article was the reason for the emergence of such an approach to software design as API First.
API First – a modern trend in methodologies for developing software solutions, the popularity and necessity of which is largely, but not exclusively, due to the success of platforms and projects focused on the web and the mass online user (“car, platform, crowd“). We will assume that API First is a software development methodology that considers the API as a foundation or final product around which organizational processes and development itself are built. With this approach, it is expected that client applications (for example, developed by you or the SDK community) will run on top of your API, and the API itself will be the “pulse” of your project. Close attention and heavy workloads are some of the inevitable challenges to keep in mind when developing API First projects. Two of the most important things we focus on are the consistency and reusability of your API.
In other words, when developing, you need to provide public contracts for interacting with the API, as well as maintain backward compatibility and consistency.
API consistency is:
Standardization. Using the standards and best practices used in the design and development of APIs, using our own Guideline for writing specifications;
Names. Use thoughtful field and entity names that accurately describe your product concepts. Detailed descriptions of methods, lack of abbreviations and jargon in the description;
Consistency. The various parts of your API use intuitive and consistent call names and signatures.
Since API First focuses on the API as the first and most important user, it becomes critical to shape approaches that require contracts (interfaces) to be defined early in the design or development phase. You can read more about this Here.
In practice, the “API First” approach (for example, when using the OpenApi/Swagger standard) is applied in one of two views:
Design first.
code first.
The second point is a more traditional approach to creating an API, in which code development occurs after the main business requirements are determined, and documentation is eventually created from the code (Fig. 1).
The disadvantages of the Code First approach are detailed in the article. Design API First:
Narrow places. The code-first approach means waterfall model API development, which leads to bottlenecks. API teams complete each phase in sequential order, so they cannot work in parallel.
Useless or bloated APIs. When you write code and then get feedback after multiple versions of a coded API, you often end up with bloated APIs that have unnecessary resources. You also run the risk of creating APIs that don’t help your customers at all.
Lack of documentation. Once development is complete on a project, creating documentation can seem like a giant chore. Therefore, it often becomes a secondary task rather than a priority, and is never completed.
Lost time and money. Making changes to an already coded API is much more expensive than making changes to an API project. You typically have to comb through and write a lot of code to fix the API after receiving user feedback. If you wrote the code first and didn’t do the documentation, you might end up creating new versions of endpoints and API, because no one on the team remembers how the code works.
The Design First approach suggests developing an API contract first before writing any code. First, the design is carried out, after which its results can be converted into a human and machine-readable contract (API). For example, such as the OpenAPI document from which the code is generated (Fig. 2).
The Design API First approach has a number of advantages:
The backend and frontend commands can be implemented in parallel based on generated APIs and the use of mocking tools (Prism, mockserver, Imposter).
The time to receive the first feedback on the results of the project implementation is reduced. After the APIs are ready, you can already “feel” them and get a general understanding of how the product will work.
API development is handled by more skilled architects (perhaps with the involvement of developers), which allows for higher quality and more unified work.
Getting earlier feedback allows you to make adjustments (both at the level of business logic and at the level of technical implementation) to the API structure at the design stage, which allows you to remove the most time-consuming stage of implementation from the full cycle (design – implementation – testing – making changes) .
The presence of a formalized description of the API structure in the form of YAML or other JSON, which allows the use of tools for automatically generating API interfaces, eliminating developer errors and removing the mismatch between the design and implementation stages.
The use of formalized API descriptions increases the percentage of reuse of such solutions, which can be considered as separate modules implemented in other projects (for examples of such solutions, you can find in our next article “Design API First implementation example using an authentication service implementation example”).
Automatic generation of documentation that always remains up to date and does not require manual adjustment when making changes, for example, using PlantUML.
The ability to use automation for faster processing of changes, both on the backend side and on the frontend side (we will talk about the features of using automatic model generation in applications on JS frameworks in our other article “Generating models based on the specification on the side of frontend applications”) .
Of course, the actual process of using the Design API First approach is more technical. However, the additional costs incurred at the design stage are more than compensated for at subsequent stages of implementation. Getting a more complete and formalized view of the system at the stage of analytics plays a very important role in understanding its subsequent functioning and gives all participants in the process (both the customer and the development team) the opportunity to see risks and problems as early as possible and make agreed decisions about their elimination. We will tell you about the means and tools we use at SimbirSoft in our next article, which is devoted to the integration of the Design API First pattern into our software development pipeline.
Thank you for your attention!
We publish other useful materials for developers and architects in IT in our social networks – VC And Telegram.
