We implemented OpenAPI as a standard. But how do we ensure that change is reflected in the documentation? Here is what we’ve done.
You are probably familiar with the concept of OpenAPI. Previously named Swagger, it then was donated to the OpenAPI initiative as a project. The short version is: if your software exposes APIs to the World, then OpenAPI is the standard way to describe all the functionalities and requirements of your application endpoints.
Such a document is referred to as API Specifications.
In the most common cases, OpenAPI specifications are used to generate the visual Documentation of your endpoints.
There are many tools out there that you could use; feed them with your API specification and voilà! You got yourself a professional documentation portal for your API. Your users and clients will be very happy to read in detail the instructions on how to consume your endpoints.
At Founda Health we take even more advantage in having API specifications. We use it to auto generate client SDKs for our own API.
A client SDK contains functionalities that you can use to call the API from your application without having to deal with HTTP requests and responses.
Yes, you read that correctly. It is possible, thanks to various tools, to generate clients SDKs in different programming languages (PHP, Scala, Java, C#, Typescript…).
Simply feed the tool with your API specifications and it will generate many SDKs.
You can now provide developers around the World with a simple to start, simple to use client SDK written in their preferred coding language.
Now, let’s pause a second and let’s reflect on the two cases: documentation and SDKs creation.
They both are generated from the same source: an OpenAPI specification. Does this mean that they are now in sync? And when the specifications change also the documentation gets updated? The client SKDs too?
The development team at Founda Health embraced these concepts from the very beginning. We implemented OpenAPI as a standard and we took it even further. It all started with the realization that one of the most common problems in exposing an API is to keep it in sync with the documentation portal during its evolution.
So we asked ourselves: How do we ensure that when the signature of an endpoint is mutated, the change is also reflected in the documentation? Here is what we did.
We created a standalone Git repository containing the OpenAPI specifications of our API server.
This means that in one and only one place we have the description of the API and in general all the information on how to validate an incoming API request: all its properties, the required fields, data formats and more.
We generate the API documentation portal using the information present in the OpenAPI specification.
We make usage of the OpenAPI specifications when creating the API server. Yes! We have decoupled the HTTP endpoint itself from its handler.
Before – This image describes the classic API server setup where one endpoint takes the responsibility of processing the entire request:
After – Founda Health uses the information present in the OpenAPI specification to:
The great advantage of this setup is to always have the API server in sync with the Documentation portal because they are based on the same source – the OpenAPI specifications.
We optimize even further: moving into the Frontend applications. Our UI applications always consume API endpoints to read and write data.
We call them Dummy UI because there is no business logic implemented inside. What we highlighted was the repetitive tasks in writing the code to consume the API endpoints from our VueJS applications.
We decided to generate a few more components using the OpenAPI information:
This image illustrates how we saved hundreds of hours in development time by using the OpenAPI specification smartly:
We based the generation of some part of our code on the OpenAPI specifications document. It simply means that when it is updated, all the inherited components will be regenerated. This setup avoids a lot of time spent in repetitive tasks from the development so that the team can focus on adding value to the core functionalities of the Founda Health Platform.