In this post, I’d like to tell you what OpenAPI is and why you may need it.
Your Pokemons
Your status quo: you’ve got two developers. One is developing the backend of your product, the other is working on the frontend.
You’ve got an idea for a new supercool application and you want to develop it as soon as possible, so you call an experienced architect to design well in advance the ideal API for which the frontend and the backend can be developed simultaneously.
The architect develops the ideal API, describes it in one big document and issues it to the developers.
Each of the developers takes the API description, reads it carefully and implements the described API.
Measure thrice and cut once
In the long run, we’d like to get the frontend and the backend, each of which will deal with the same requests (the frontend will send and the backend will process them). Ideally, these requests should also comply with what the architect has described (although it’s not so important).
Now let’s see what must happen to make the frontend and the backend requests coincide:
- The backend developer hasn’t made any mistakes while implementing the API
- The backend developer has read the architect’s API description correctly
- The frontend developer hasn’t made any mistakes while implementing the API
- The frontend developer has read the architect’s API description correctly
If anyone makes a mistake even in one of the items, your entire project will fail. And that’s assuming that the architect doesn’t make any errors (spoiler: they all do).
It should be specially noted that heavy responsibility falls on human understanding and human communication of all technical details. The human understanding is generally rather hard to debug and test.
People are a weak link in the chain
Given the situation, the desire to minimize the human factor in the API development seems quite natural. You’d like to exclude the human factor from the moment when the architect described API in the document. (As a matter of fact, it would be great to avoid the architect’s errors, too, but the technologies haven’t advanced thus far yet).
Obviously, to make this possible, the architect should deliver not a human-readable document but a computer-readable document, i.e., some sort of formal specification for a specific API. If we have such API description, we can at least try to allot the subsequent tasks to automation.
For each programming language, there are usually not so many ways to make a “canonical” implementation of any HTTP API when using a specific framework. Frameworks usually don’t have so many ways to make a request with a JSON object in the body, nor so many ways to read an integer in the request path.
OpenAPI
It would be great to be able to describe your HTTP API once and get coinciding frameworks from this description to develop the backend and the frontend, which, considering that there is no human factor in the chain, will more likely coincide. (Provided that the frameworks have been generated without errors, which is in fact a simpler task).
And behold! This has been invented already! This is OpenAPI!
OpenAPI allows describing HTTP API formally as YAML files. A rather extensive example can be found on editor.swagger.io. There you can simultaneously view the source YAML and the human-readable HTML-page.
If the architect describes the original specification in the form of an OpenAPI specification, the interaction between the backend and the frontend can be generated automatically and will always coincide. Thus, we eliminate the human factor from the chain altogether!
More than just code generation
Code generation is just one of the OpenAPI applications. OpenAPI is an open format of HTTP API description not tied to any specific ecosystem. It allows exchanging the accurate API description between the systems which would otherwise require manual API “synchronization”.
There are a lot of tools based on OpenAPI specifications. Openapi.tools is a good source of such projects. There you can find such projects as GUI specification editors, test server generators based on specifications, search for vulnerabilities by specifications and many other things!
Using Open API allows you not only to improve the accuracy of your API descriptions, but also to get access to a larger number of tools which might be useful for the project development.