Posted on September 6, 2021 by Ilya Kostyuchenko

The Confusion Around Your API

How to prevent your APIs from scattering

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.

Your team has Architect, Backend Developer, and Frontend Developer

The architect develops the ideal API, describes it in one big document and issues it to the developers.

Architect develops the API spec

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).

Backend and frontend developers implement the API their own way

Now let’s see what must happen to make the frontend and the backend requests coincide:

  1. The backend developer hasn’t made any mistakes while implementing the API
  2. The backend developer has read the architect’s API description correctly
  3. The frontend developer hasn’t made any mistakes while implementing the API
  4. 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.

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!

Code generation guarantees the implementations will coinside

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.

Recommended

You may also like

Want to know more?
Get in touch with us!
Contact Us

Privacy policy

Last updated: 1 September 2021

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.

Information Collection And Use

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").

Log Data

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

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.

Security

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.

Changes To This Privacy Policy

This Privacy Policy is effective as of @@privacePolicyDate​ and will remain in effect except with respect to any changes in its provisions in the future, which will be in effect immediately after being posted on this page.

We reserve the right to update or change our Privacy Policy at any time and you should check this Privacy Policy periodically. Your continued use of the Service after we post any modifications to the Privacy Policy on this page will constitute your acknowledgment of the modifications and your consent to abide and be bound by the modified Privacy Policy.

If we make any material changes to this Privacy Policy, we will notify you either through the email address you have provided us, or by placing a prominent notice on our website.

Contact Us

If you have any questions about this Privacy Policy, please contact us.