Cover image by Mattia Serrani on Unsplash.
With software products being more and more just a bunch of micro-services and third-party APIs mashed together, it gets more crucial for us to get their structure in order.
GraphQL already did this at its inception by coming with a whole specification that describes how APIs of its type should behave. In the RESTful API landscape, things went a bit more wild-west. However, even if not all backend devs know, there are various specifications for REST APIs too!
One of the best known is the OpenAPI spec or short OAS.
Enter OpenAPI
The OpenAPI specification was known as Swagger until version 3.0 got released in 2017 and it was renamed to OpenAPI. It's a language-agnostic way to describe a RESTful API that can be used to generate code-stubs and documentation.
Its idea is to specify a REST API with a YAML document. This document can be used to generate documentation and methods for API endpoints. While APIs are generally used to decouple software, the OpenAPI spec also allows us to decouple the public interface of our API from our implementation details.
Business and design teams can define the features they need, and an engineering team can create an OpenAPI YAML document that defines all these in technical terms.
Then the frontend and backend teams can use this document as a corner-stone to do their implementation. Both able to choose their technologies as they see fit.
The OpenAPI ecosystem even provides tools to create mock APIs, so the frontend developers have something more practical to work with.
Why should we use it?
There are a bunch of reasons why adding an OpenAPI specification between frontend and backend can be valuable.
Design-First
We can define the whole API with types and examples for every endpoint before we start implementing it. With tools that generate mock-APIs, we can verify that everything looks the way we intended. We can refine our API design by simply iterating over the specification document.
Code Generators
OpenAPI is the REST specification with the most languages supported by their code-generators. It generates server stubs in the language of our choice, and we have to wire it up with our backend services and databases.
Tooling
The Swagger specification got donated to the OpenAPI foundation and renamed to OpenAPI specification. However, there is a giant ecosystem of tools created under the Swagger brand that can be used to speed up the API development process.
They can be used to generate automatically:
- documentation
- tests
- mock servers
Huge Userbase
OpenAPI is used and backed by many big companies and can be seen as their condensed knowledge of building thousands of APIs over the years. This knowledge alone is invaluable if we start out building our first API, but it's also good to know that there are many people out there to help if something isn't bright.
Stable Implementation
As already mentioned, the OpenAPI spec was known as Swagger spec until 2017, so it doesn't surprise that it isn't the first version of the spec. It's version 3.0 where the rebrand from Swagger to OpenAPI happened.
The spec doesn't change too often now and can be considered mature at this point.
Why we should not use it?
The OpenAPI specification isn't a silver bullet that can solve all problems that arise when building an API.
No RESTful API
If we use GraphQL, we don't need OpenAPI. However, sometimes it isn't so obvious. Sometimes we get the task to build an API, think it will be RESTful, but when learning about the features that are needed, we are better off with something non-RESTful.
If we build, for example, an event-based system, something like gRPC or AsyncAPI may be a better fit for it.
Added Complexity
As with all tools we add to our projects, there is the risk of added complexity that doesn't bring any benefits. Many people got burned by SOAP in the past, even if the OpenAPI spec isn't as massive, it can lead to problems when not used correctly.
We need to find some integration for the framework of our choice, or we need to switch to a framework that supports OpenAPI specifications. Then we could find out that the performance of the other framework isn't good enough or it's not maintained anymore.
Also, every line of code we write is a potential source of errors, even if it is YAML.
The developers building the API also have to acquire the skills to use OpenAPI, and it's tools.
Substituting Missing Skills
OpenAPI can be overkill when we already got senior API devs who know their trade, but it can help to be a guideline for less experienced devs. The problem is, we need to train these people and not just hope OpenAPI will save us from lousy API design choices.
It should be a tool to help people and not a replacement for educating them.
Tools
There is an ample supply of tooling to make work with OpenAPI even simpler. Converters, data-validators, documentation, editors, mock-servers, and generators for tests and SDKs.
Most of it can be found here: https://openapi.tools/.
Alternatives?
There are, of course, many alternatives to the OpenAPI spec, while they have lower adoption rate, it could be that they are pushing just the right buttons of our developers and are easier to understand and use.
- RAML - The RESTful API Modeling Language RAML is a bit more lightweight than OpenAPI but still based on YAML.
- API Blueprint. A powerful high-level API description language for web APIs. API Blueprint uses its own (non-YAML) syntax.
Conclusion
OpenAPI is one of may attempts of casting decades of API building skills into a specification. Seemingly even the one with the most mind-share and money behind it.
The OpenAPI Initiative is part of the Linux Foundation, which makes it a bit more trustworthy and at least looks like it won't go away soon.
It isn't a silver bullet and probably not for everyone, but if used right, the added complexity can save quite a bit time in documentation writing and test creation later.
Moesif is the most advanced API Analytics platform, supporting REST, GraphQL and more. Over 2000 organizations use Moesif to track what their most loyal customers do with their APIs. Learn More
This post was originally published on the Moesif blog.
Top comments (16)
There are also several frameworks that will generate OpenAPI specs from the implementation. Sort of turns the whole process on its head, but its a great workflow for, say, a Python developer who is very comfortable writing in their framework of choice but doesn’t want to learn the OAS DSL.
FastAPI and Flask-Restplus are the two I use. Great for writing the API in Python then taking advantage of OAS to generate client libraries.
Good to know!
I read about GraphQL frameworks moving from schema-first design to creating schemas from the implementations, or even directly from the database schema.
Nice that such tools also exist for OpenAPI!
Yep. I do development in .NET Core and we can generate OpenAPI spec from code using NSwag or Swashbuckle. Very easy.
I'm currently working at a company where there is an API first approach, using REST with open API. It seems a great idea, especially to control the public APIs. However, especially compared to GraphQL there are several things not so nice.
If your using advanced features, the Java generation doesn't always produce the correct result. Which means you need go back to a simpler way, less well describing the API.
Although we put authorizations in the definition, they are not shown in the tool used to inspect the API. Also because of the authorizations you can't test the endpoints from the tool. Worse is, besides testing, there is no enforcement on implementing the correct authentications.
If you want to know what's available at a certain environment, you need to know which version of the generated API is used there. While with GraphQL you could just inspect the endpoint.
I also worked with REST without using either OpenAPI or swagger, and that was a lot worse. As we had to make sure the manual written documentation was kept in sync with the actual implementation.
Yes, I also read that the generated code is often awful.
Awful would be great. But as soon as you start using things like anyof etc. it becomes unusable. I might give it a try some day to make it better. It would be very nice if it was better supported, and for example when creating GraphQL based on OpenApi it could also use all of this information.
In the javascript ecosystem, NestJS is absolutely amazing to work with when generating an OpenAPI document.
As it’s based off typescript, you can add property decorators to your models, and it simply works when you create your endpoints!
See for yourself on their documentation.
Didn't know NestJS used OpenAPI!
Question, Is there an easy way to set up the authentication and billing systems around APIs? I think, several times that is way harder to do than designing the actual API.
I had the impression most frameworks would offer auth integrations.
But payment often is a problem. Sometimes you get a basic plugin, but getting the payment-flow right requires to dig so deep that you end up implementing the stuff almost from scratch.
I now remember we used tyk.io/ at my previous workplace.
My experience with openapi,
The specification was good but swagger tools sucks.
openapi + postman = awesome
Any other tool recommendations? I would expect using OpenAPI directly is a bit cumbersome.
Looks great. I'll check it out.
Note that OpenAPI also assists in generating clients. This enables, much like other IDLs, the server provider to support clients in a multitude of languages without a large increase in cost. :)
You're totally right!
If you build an API SaaS company, having clients for all the popular languages can be very important, getting this from OpenAPI can save money and time!