In the dynamic world of microservices, anything can change - any component can be rewritten in a different language, using different frameworks and architecture. Only contracts should remain unchanged in order to be able to interact with the microservice from the outside on some permanent basis, regardless of internal metamorphoses. And today we will talk about our problem of choosing the contract description format and share the artifacts we found.
Post prepared ΠΈ
Microservices. When developing Acronis Cyber ββCloud, we realized that we could not get away from them. And designing a microservice is impossible without formalizing the contract, which is the interface of the microservice.
But when a product contains more than one component, and contract development becomes a regular activity, you involuntarily begin to think about process optimization. It becomes obvious that the interface (contract) and implementation (microservice) must match, that different components must do the same things in the same way, and that without a centralized decision making for all these decisions, each team will have to spend time again and again getting them. .
Diagram of Amazon microservices from Werner Vogelis, Amazon CTO
What is the dilemma? De facto, there are two ways for microservices to interact - HTTP Rest and gRPC from Google. Not wanting to get involved in the Google technology stack, we chose HTTP Rest. Annotations to HTTP REST contracts are most often described in one of two formats: RAML and OAS, formerly known as Swagger Therefore, each development team is faced with the need to make a choice in favor of one of the standards. But, as it turned out, making this choice can be very difficult.
Why are annotations needed?
The annotation is needed so that an external user can easily figure out what can be done with your service through its HTTP interface. That is, at a basic level, the annotation should contain at least a list of available resources, their HTTP methods, request bodies, enumeration of parameters, indication of required and supported headers, as well as return codes and response formats. An extremely important element of the contract annotation is their verbal description (βwhat happens if you add this query parameter to the request?β, βIn which case will the 400 code return?β)
However, when it comes to developing a large number of microservices, you want to get additional benefit from the written annotations. For example, based on RAML / Swagger, you can generate both client and server code in a huge number of programming languages. You can also automatically get the documentation for the microservice and upload it to your developer-portal :).
An example of a structured contract description
The practice of testing microservices based on contract descriptions is less common. If you wrote both the annotation and the component, then you can create an autotest that checks the adequacy of the service with different types of input data. Does the service return a response code that is not described in the annotation? Will it be able to correctly process deliberately incorrect data?
Moreover, the high-quality implementation of not only the contracts themselves, but also the tools for visualizing annotations makes it easier to work with the microservice. That is, if the architect has qualitatively described the contract, on its basis, designers and developers will implement the service in other products without additional time costs.
For additional tools to work, both RAML and OAS have the ability to add metadata that is not provided for by the standard ().
In general, the scope for creativity in the use of contracts for microservices is huge ... at least in theory
Comparison of a hedgehog with a snake
Currently, the priority direction of development in Acronis is the development of Acronis Cyber ββPlatform. Acronis Cyber ββPlatform is a new point of integration of third-party services with Acronis Cyber ββCloud and the agent part. While we were happy with our internal RAML APIs, the need to publish the API again raised the question of what annotation standard would be best for our work?
Initially, it seemed that there were two solutions - these are the most common developments of RAML and Swagger (or OAS). But in fact it turned out that there are at least not 2 alternatives, but 3 or more.
On the one hand, there is RAML, a powerful and efficient language. Hierarchy and inheritance are well implemented in it, so this format is more suitable for large companies that need a lot of descriptions - that is, not one product, but many microservices that have common parts of contracts - authentication schemes, identical data types, error bodies.
But the developer of RAML, Mulesoft, has joined the Open API Consortium, which is developing . Therefore, RAML has suspended its development. To imagine the format of the event, imagine that the maintainers of core Linux components have gone to work for Microsoft. This situation creates the prerequisites for using Swagger, which is developing dynamically and in the latest - the third version - almost catches up with RAML in terms of flexibility and functionality.
If not for one thing but ...
As it turned out, not all open-source utilities have been updated to OAS 3.0. For microservices in Go, the most critical will be the lack of adaptation under the latest version of the standard. However, the difference between Swagger 2 and Swagger 3 is β . For example, in the third version, the developers:
- improved description of authentication schemes
- JSON schema support
- upgraded the ability to add examples
The situation turns out to be funny: when choosing a standard, you need to consider RAML, Swagger 2 and Swagger 3 as separate alternatives. However, only Swagger 2 has good support for the OpenSource toolkit. RAML is very flexible... and complex, and Swagger 3 is poorly supported by the community, so you'll have to use either your own tools or commercial solutions, which tend to be quite expensive.
However, if there are many nice features in Swagger, such as a ready-made portal , to which you can upload an annotation and get its visualization with a detailed description, links and connections, then for a more fundamental and less friendly RAML there is no such possibility. Yes, you can search for something among the projects on GitHub, find an analogue there and deploy it yourself. However, in any case, someone will have to maintain the portal, which is not so convenient for basic use or test needs. In addition, swagger is more βunprincipledβ, well, or liberal - it can be generated from comments in the code, which, of course, goes against the API first principle and is not supported by any of the RAML utilities,
At one time, we started working with RAML as a more flexible language, and as a result, we had to do a lot with our own hands. For example, one of the projects uses the utility in unit tests, which only supports RAML 0.8. So I had to add crutches so that the utility could βeatβ RAML version 1.0.
Do you need to choose?
Having fooled around with adding an ecosystem of solutions for RAML, we came to the conclusion that we need to convert RAML to Swagger 2 and already carry out all the automation, verification, testing and subsequent optimization in it. This is a good way to use both the flexibility of RAML and the community tooling support from Swagger.
To solve this problem, there are two OpenSource tools that should provide contract conversion:
- is a currently unsupported utility. In the process of working with it, we found that it has a number of problems with complex RAMLs that are βsmearedβ over a large number of files. This program is written in JavaScript and performs a recursive traversal of the syntax tree. Because of dynamic typing, it becomes difficult to understand this code, so we decided not to waste time writing patches for a dying utility.
- - a tool from the same company that claims to be ready to convert anything and everything, and in any direction. To date, support for RAML 0.8, RAML 1.0 and Swagger 2.0 has been announced. However, at the time of our research, the utility was still damp and unusable. Developers create a kind allowing them to quickly add new standards in the future. But so far it just doesn't work.
And this is not all the difficulties we have encountered. One of the steps in our pipeline is to check that the RAML from the repository is correct with respect to the specification. We have tried several utilities. Surprisingly, they all swore at our annotations in different places and with completely different bad words. And not always on business :).
In the end, we settled on a now obsolete project, which also has a number of problems (sometimes crashes out of the blue, has problems when working with regular expressions). Thus, we did not find a way to solve the problems of validation and conversion based on free tools, and decided to use a commercial utility. In the future, as OpenSource tools become more advanced, this task may become easier. In the meantime, the labor and time costs for βfinishingβ seemed to us more significant than the cost of a commercial service.
Conclusion
After all this, we wanted to share our experience and note that before choosing a tool for describing contracts, you need to clearly define what you want from it and what budget you are ready to invest. If you forget about OpenSource, there are already a large number of services and products that will help you check, convert, and validate. But they are expensive, and sometimes very expensive. For a large company, such costs are tolerable, but for a startup they can become a big burden.
Define a set of tools that you will use later. For example, if you just need to display a contract, it will be easier to use Swagger 2, which has a beautiful API, because in RAML you have to raise and maintain the service yourself.
The more tasks you have, the wider the need for tools will be, and they are different for different platforms, and it is better to immediately familiarize yourself with the available versions in order to make a choice that minimizes your costs in the future.
But it is worth recognizing that all ecosystems that exist today are imperfect. Therefore, if there are fans in the company who like to work in RAML because βit allows you to express thoughts more flexiblyβ, or, conversely, they prefer Swagger because βit is more understandableβ, it is best to leave them to work in what they used to and want to, because the toolkit of any of the formats needs to be finalized with a file.
As for our experience, in the following posts we will talk about what kind of static and dynamic checks we perform based on our RAML-Swagger architecture, as well as what kind of documentation we generate from contracts, and how it all works.
Only registered users can participate in the survey. , you are welcome.
What language do you use to annotate microservice contracts?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (a.k.a.)
-
Blueprint
-
Other
-
Not using
100 users voted. 24 users abstained.
Source: habr.com