Introducing a new friend: Open API
Writing an API from scratch can be quite fun and informative for developers.
Yet, maintaining dozens of APIs in a company is another 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 centralized place, manually merging conflicts as and when they happened, and 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 is in your source code, in your documentation, in your server settings, perhaps in your application and even in your demo code.
Being in multiple places means that your team had to write it multiple times, which is time-consuming and not aligned with the 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.
Open API is a specification. The core concept is to have the API definition in a unique, centralized, versioned file.
- Unique because only one file contains the definition
- Centralized 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 Open API 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 is maintained by Swagger, a company that builds API tools.
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 another 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 visualize its content thanks to the many open-source visualizers 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 Open API 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, but look: 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.
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, …).
Those services will have to know the design of your API. Good news, we have our Open API file!
AWS, Azure, Google Cloud and other providers support the Open API 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
Open API 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.
Still want more?
There are many other services, be they open-source or SaaS, that can brighten up your journey in constructing professional APIs. They 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.
Simon Guilliams, Developer at Ponicode