In this post, I’d like to tell you what OpenAPI is and why you may need it.
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.
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:
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.
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.
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!
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.
Typeable OU ("us", "we", or "our") operates https://typeable.io (the "Site"). This page informs you of our policies regarding the collection, use and disclosure of Personal Information we receive from users of the Site.
We use your Personal Information only for providing and improving the Site. By using the Site, you agree to the collection and use of information in accordance with this policy.
While using our Site, we may ask you to provide us with certain personally identifiable information that can be used to contact or identify you. Personally identifiable information may include, but is not limited to your name ("Personal Information").
Like many site operators, we collect information that your browser sends whenever you visit our Site ("Log Data").
This Log Data may include information such as your computer's Internet Protocol ("IP") address, browser type, browser version, the pages of our Site that you visit, the time and date of your visit, the time spent on those pages and other statistics.
In addition, we may use third party services such as Google Analytics that collect, monitor and analyze this ...
Cookies are files with small amount of data, which may include an anonymous unique identifier. Cookies are sent to your browser from a web site and stored on your computer's hard drive.
Like many sites, we use "cookies" to collect information. You can instruct your browser to refuse all cookies or to indicate when a cookie is being sent. However, if you do not accept cookies, you may not be able to use some portions of our Site.
The security of your Personal Information is important to us, so we don't store any personal information and use third-party GDPR-compliant services to store contact data supplied with a "Contact Us" form and job applications data, suplied via "Careers" page.