In Karumi, we are always looking for technologies and tools that help us and help our clients to produce, evolve, and maintain their products with the highest quality and robustness in mind. Most of the time, we have to develop some mobile clients that will consume an already established backend API; or develop both the backend services and the clients using them.
One tool that has been hanging in our belt for the last couple of years is OpenAPI, previously known as Swagger and we are more than pleased with it, so now, it's my turn to convince you about why you should be using it if you work at any side of an API.
This first blog post is the beginning of a series that will guide you in defining, offering, and consuming an API built from scratch.
What's OpenAPI?
OpenAPI is a specification that defines a standard that can be used to describe RESTful APIs in an agnostic language manner that helps programmers to understand and modify it.
Based on that specification, several tools will help you to automatically generate the code that exposes that service, the code consuming it, and even the documentation about it.
Why should I use OpenAPI?
Automatization.
The feature that got our attention to invest time in OpenAPI was the ability to generate the API clients automatically, so we don't have to bother anymore about model changes and parsing issues for an updated response. Instead of that, once the specification is modified, we run our client generator, and our project is ready to be using the latest changes offered.
You may end up changing some parts of your code to adopt that new client changes, but that's something you would have to do anyway.
If your API client is generated automatically out of your project, it can be integrated, handled, and consumed like any other third party dependency. Besides that, it avoids all the usual boilerplate you have to program in every project.
OpenAPI can generate the code for most of the programming languages out there, so once you've defined the API, you can build in a matter of seconds the client for iOS and Android, to name some platforms.
Single point of truth.
Once you describe your API (that means endpoints, objects, path, etc.) using one single file, you could convert that description into a specific implementation; it does not matter if it's server-side or client-side. That code will be a product of that description, once you change it there, all the "artifacts" produced out of that file could be regenerate to be used.
That avoids API integration failures like errors parsing invalid responses due to a misalignment between the back-end-offered API and the client-consumed API.
Definition first.
Suppose you decide to go all the way down with OpenAPI and produce the API integration automatically for both the backend and the clients; you will be forced to define your API before implementing anything about it, in any of the sides of it, obtaining a 100% framework biases-free API.
What does it mean? It means that the API definition will be the product of a well-thought process instead of just returning the models the backend already have around. This will force both sides to adapt themselves to work with the API being defined; this approach will put in a 50/50 relationship the client/server weight to describe how they communicate.
Another benefit of having the API definition first is that you can implement both sides without interacting with each other. As you know, there is a contract that is being respected at both sides of the API. If you are implementing a mobile client, you can even develop your tests using HTTP stubs to respond with responses that will be the same as the server will respond.
100% Human readable with the documentation always up-to-date.
The OpenAPI definition file can be described in JSON or YAML, being both quite easy to read as a human and easy to modify if required. This is quite important. It's way easier to discuss how to make some changes over an easy-to-read document than discuss those changes over a specific programming language or framework.
There is something worse than having no documentation, and that is having out-of-date documentation. As a side-effect of the single point of truth, if you whole API specification is kept in just one format, and several tools can automatically process it, and one of that tools is the documentation generator, so your API documentation (even if it is just for internal usage) won't be outdated ever again.
Industry standard.
OpenAPI is the current defacto industry standard for API definition, so offering your API using this specification guarantees that any other company will be able to use your services out-of-the-box without any extra setup. That could seem uninteresting for a lot of companies that create their API to be closed, but this technology does not force you to open anything, it will help you to have your API specified using a well-known tool so it can be published if required.
Open-Closed principle down to the roots.
What if I need a specific implementation for my client/server, and it's not present in the current languages? No problem at all, you can define your own template.
OpenAPI under the hood will use a templating-engine to transform any custom template into some source code. This isn't as easy as invoking it for Kotlin or Scala, but you can create your generation without substantial modification in the generator.
What's next?
In the next blog post, we will define a basic API to show how this technology work, and we will generate the API interface for a Spring Boot server and an iOS client that will consume it.
Photo by Neven Krcmarek on Unsplash