Introducing OpenAPI
Writing an API from scratch can be quite fun and informative for developers.
Yet, maintaining dozens of APIs in a company is whole other kettle of fish.
Back in the 70s, source control didn’t exist. Each developer had their own local copy of the company’s source code. Then people started storing the code in a centralised place, manually merging conflicts as and when they happened, before eventually, Git arrived.
If you have an API, chances are it’s been defined in multiple places, like source code back in the 70s. It's in your source code, in your documentation, in your server settings, perhaps even in your application and demo code.
Being in multiple places means that your team had to write it multiple times, which is time-consuming and not aligned with business interests. Problems arise when you need to change or update your APIs:
- How do you make sure that the documentation is always up-to-date with respect to the API implementation?
- How do you make sure that the developers have correctly implemented what the API architects decided?
This is where a new friend can help: OpenAPI.
OpenAPI
OpenAPI is a specification. The core concept is to have the API definition in a unique, centralised, versioned file.
- Unique because only one file contains the definition
- Centralised because other teams know where your definitions are located
- Versioned because one file will always contain the latest version of your definition
- In a file so that the API architecture is distinct from the API implementation
While I was following this concept, I discovered so many great benefits company-wise that I wanted to share it.
In practice, the file will be written in YAML or JSON and will be versioned using Git, or another version control system. It will contain all the information about your API structure: name of the endpoints, their methods, their content type, the parameters, the format of the response, etc. You can find out more here.
The definition is ruled by a standard, which is called OpenAPI Specification. It is currently on its third version, so we call it OAS3. This is the best known and respected standard for API design.
OAS3 was created by Swagger, a company that builds API tools. In 2015, it was donated to the Linux Foundation under the OpenAPI initiative.
Lots of tools and services can read OAS3 definitions, and provide functionality based on them.
Let’s look at some of the benefits:
Design Versus Implementation
In a small company, everyone wears many hats. People who imagine the API will also be the ones who will implement the endpoints.
In a medium-sized company, the API design will undergo validation by at least one other person or team. How will you send the API design to your managers? Will you send them an email with one bullet point per endpoint? OpenAPI to the rescue - you have a definition already, and you can let others visualise its content thanks to the many open-source visualisers available.
In a large company, the API will be designed by software architects and implemented by developers. How do you make sure that the developers have correctly implemented what the API architects designed?
This is where OpenAPI really hits: it guarantees consistency between the design and all implementations, be it source code or a demo client. This is magnified every time your API is updated.
Even startups can take advantage of this. Starting from the ground up using Open API has a low cost, and since they will hopefully scale someday, it’s in their interest to have a clear separation between design and implementation.
A Server in a Second
Dozens of tools can read your definition. One of them is called OpenAPI generator, and it can generate code for you, supporting more than a hundred languages or frameworks!
Say you want to implement an API in Go using the gin framework. Just run this:
openapi-generator generate -i ./product-api.yaml -g go-gin-server -o ./server
In a second, you will have a fully working server responding to your endpoints.
Of course, you still have to implement the endpoints. However, while implementing an endpoint, you don’t have to go back to your YAML definition to see what that endpoint should return. The generator wrote all data structures for you. You just have to fill in the fields in each structure, without worrying about the details. Isn’t that the whole point of an API?
I love this. That tool alone saved me hours not only by writing low added value code for me, but by enabling me to focus on the spirit of my code.
A Client in a Second
Did you just save an hour with this tool? Let’s save three.
Let’s imagine your company has a website that uses your API in the backend. You also have demo code. Oh, and a mobile app too.
I don’t recommend your team manually write three clients for your API because it will be expensive to maintain.
Just use openapi-generator again! It supports so many languages for both servers and clients, and the output code is guaranteed to be 100% up-to-date with your API design and your documentation.
The generator was conceived as a one-off tool, but you can easily achieve automatic code upgrade by spending a bit of time in automating it. That way, you can run the generator again whenever your definition changes.
Cloud Platforms
At some point, you will have to put your API in production. Most cloud providers offer useful services to secure, scale and accelerate your API (DDOS protection, error monitoring, permission management, version control, scale groups, …). These services will have to know the design of your API. Good news, we have our OpenAPI file!
AWS, Azure, Google Cloud and other providers support the OpenAPI specification natively. You just need to upload the file to the platform. This is a huge time saver since you don’t have to manually set-up and update each API at each change.
Your Users Will Love You
OpenAPI can also make life easier for your users: by sharing your definition, you will allow them to generate their own client for your API in the language of their choice.
You can even generate a client for them to interact with your product. This removes a barrier to user adoption and can be a competitive advantage.
Want More?
There are many other services, be it open-source or SaaS, that can brighten up your journey in constructing professional APIs. These can:
- Scaffold API documentation
- Generate SQL tables based on your data structures
- Open a GUI to test your endpoints like Postman and Postwoman
- Mock servers
- So much more
Open API is not the only API specification format, but I found it to be the most integrated with other tools.
At Ponicode, we want to be as efficient as possible in our API development process. All our microservices have a definition file at the root of the repository, and it has proven to be a great time saver.