A Single Specification Format as a Microservice API Artifact when Using API-First

Volushkova Vera L'vovna PhD in Technical Science Associate Professor, Department of Computer Science, Tver State University 170004, Russia, Tverskaya oblast', g. Tver', pr-d 2-Oi stakhanovskii, 47 w2lvera@gmail.com Other publications by this author

Volushkova Aleksandra Yurievna Java Backend Developer, Axenix LLC 115054, Russia, Moscow region, Moscow, Paveletskaya str., 2,p.2 sobakasasha114@gmail.com

API-First is a way of creating enterprise applications, in which the API has the highest priority and is created at the initial design stage ^[1][2]. Microservices play an important role in corporate applications. When using API-First, the creation of the service should start with the API. This is a rather rare approach to creating microservices.

The average IT manager considers creating an API before creating a microservice to be an inefficient, outdated, classic way of working on a project.  API-First is actually the implementation of the traditional stages of development: analysis, design, development. It is believed that Agile is not an outdated approach to design^[3].

The proposed approach to API design can also be used in the Agile methodology. In Agile, it is possible to create documentation before the task itself is completed. The use of Agile methodology can lead to different protocols of interaction between microservices due to multiple changes and the implementation of different versions. The methodology proposed in the paper for creating server applications allows you to maintain a single format of interaction protocols in the form of an API artifact. 

The microservice API has its own creation sequence in which an API artifact is created. The service being designed has a dependency on the API artifact. This ensures the significance of the specification in the artifact. Thus, the order of development of the microservice API implies the initial creation of the API, and then its implementation in the world service. The above procedure for creating services is the main one when using the API-First paradigm, but does not define it.  From the definition of First, it follows that the creation of an API interface is the first stage in application development.  The dependence of microservices on the API is shown in Figure 1.

Figure 1. Microservices API

Creating a single API within API-First allows you to:

· develop simultaneously: API-using application, tests, API implementation;

· develop an application using the API in any language;

· have a mandatory design stage — API development;

· always have an up-to-date API specification;

· reduce the possibility of design errors;

· reduce labor costs for design.

Creating a single API can change the classic code-frist development cycle ^[4], which consists in the fact that the API is created after the services are created. Let's say a new microservice is being implemented or the API of an existing service is being changed. At the same time, it is necessary that the API specification meets the business requirements. In the classic development cycle, it is allowed to check API compliance with business requirements only after API implementation. If an error is found in the specification, there will be changes in both the specification and the implementation of the API, as shown in ^[5]. Testing teams and teams creating an application using the API must wait for the API implementation to be completed. This process is shown in Fig. 2

Figure 2. The development process in the Code first design architecture

The API-First architecture makes it possible to avoid a long wait for design teams. The developed API must be implemented both in the application using the API and in the service implementing the API. To successfully promote the API, it is proposed to apply the TDD (test-driven development) design method^[6][7]. At the stage of creating tests, it is allowed to check the API specification.

We can say that from the moment the tests are developed, the stage of creating a new version of the API begins. At the same time, the team creating the client develops tests in which the API call affects the operation of the client application. In the tests of this stage, the result of the API call is reproduced using Mock. This is how the use of the service API in further developments is simulated. With the help of these tests, you can additionally control the API specification, namely:

· does the API meet the conditions;

· is it possible to optimize the number of service calls;

· whether the transmitted information meets the requirements.

Such testing will not change the effectiveness of the team. Performance may even improve if a bug is found.

Tests can be created both in an application using the API and in a service implementing the API. Tests in the service determine whether it is possible to implement the requirements specified in the API specification, namely, whether the available and provided data is sufficient. Thanks to testing, API design errors will be detected even before it is created. This makes it possible to correct the design flaws of the API when designing it. The API before implementation is much easier to change than the service itself. The development process in the API-First architecture using the TDD technique is shown in Figure 3.

Figure 3. The development process in the API-First architecture using the TDD technique

If the API implementing application is a client application, the simultaneous operation scenario is also observed. The frontend team starts working immediately after the release of the final version of the API. The test bench is deployed following the implementation of the API.  Installing the service on the stand allows the testing team to get started.

The above design architecture allows all API implementing teams to work in parallel. At the same time, API specification errors are detected earlier than in the Code first design architecture.

The process of creating software in the API-First architecture when using the TDD technique gives the following advantages:

· simultaneous work of different development teams;

· the correctness of the API documentation, which will not differ from the API implementation documentation because there is a special API product that implements the service and the client of this service;

· detection of errors in the microservices API before their development, because the design highlights the stage of API creation according to the specification.

Let's consider how to practically create a single specification format as an API artifact of a microservice.  We will accept the following provisions.

An API application consists of two projects – API creation and API implementation.

The API specification is a SNAPSHOT API, which is a separate artifact. API changes first mean changing the API specification on which the service implementing the API and consumer applications depend. The teams creating client applications take the modified API artifact. Then they check whether the created API is suitable for the team. In parallel, based on the API specification, the team creating the services has the ability to generate tests for the API.

Interface development is a complete project. Therefore, the team creating the application using the API and the team implementing the interface service have the opportunity to check the correctness of the specification and create a release API artifact.

The http API is described using the OPENAPI 3 specification^[8].

Let's look at how this protocol is used in an application created in springboot. The project is built using the following steps:

· API artifact development;

· formation of models on the server, creation of interfaces;

· creating client code.

The artifact API assembly consists of: checking the specification, creating an artifact, publishing an artifact. 

To create an API project, you need to complete seven steps, which are described in detail in ^[9].

API artifacts appear in the repository after building projects for the formation of interfaces. API artifacts are presented as a zip archive. The archive has one file. API artifacts will be included as dependencies in our projects.

For example, if we consider two ApiFirstMockClient projects, ApiFirstMock and the nexus repository, then the inclusion of dependencies is shown in Figure 5.

Figure 4. API artifacts as dependencies

Let's show you how to form an application on the server, while using the API in another service. Building a server application project includes: extracting an API artifact from the repository, unpacking this artifact, generating code according to the specification and including it in the project source directory.

How this sequence is performed is shown in ^[9].

As a result of these four stages, the openApiGenerate stage will be added to the project. The models on the server are created automatically based on the specification. Interfaces will also be generated. The generated interfaces can be accessed when creating controllers.

Consider creating client code. In this example, the client is represented by an application on the server. How the server application is generated is described above.

The assembly of the application project consists of four steps: extracting the client interface and the server interface from the repository, unpacking artifacts, generating code according to the relevant specifications and connecting to the project source directory.

For more information about creating a server and client, see ^[9].

Generating a Feign client ^[10], which simplifies writing web service clients, is also described in detail in ^[9].

The article discusses the creation of microservices using the specification as an API artifact. The development process using the API-First design architecture and TDD techniques is proposed. This way of designing microservices allows:

· Use the API developed by another team, regardless of the project language.

·         Perform simultaneous creation of different parts of the project. Testers, the API client creation team, and the service development team implementing the interface can work simultaneously using a ready-made API. This reduces the development time.

·       Qualitatively document methods and models, due to the mandatory preliminary description of the interface.

·       Reduce the amount of manual program writing, because the code is generated automatically from the specification. The interface documentation has a convenient visual representation (swagger-ui ^[11]). The documentation and the code will be coordinated due to the fact that it is based on the documentation that the service program is created. Therefore, the specification will always be represented by the current version.

·       Identify API design errors earlier than in the code-frist design architecture by using parallel testing and working with the interface before its implementation. This minimizes the costs caused by errors in the documentation.