How we reduce the time required for clients to integrate our APIS by 50%
Reducing the complexity faced by clients
Ever since 2014, operations have grown exponentially. Our clients come from different parts of the world and different types of industries. Our team has been constantly pushing out new products and API endpoints to cater to the needs of our clients. Till this date, we have more than 60 API endpoints that range from new user registration to disbursements of funds.
This complexity increases the time it requires a client to integrate our APIs, which resulted in poor developer experience.
To this end, we often compose client-specific API documentation for our customers, telling clients which API endpoints will be suitable for their use case and saving their time as not all of our APIs are needed depending on their region and requirements.
Challenges of client-specific API documentation
While many customers found this tailored API documentation valuable, there was an inherent problem in keeping them updated.
- Our APIs are changing at an exponential rate.
- Any changes made to the APIs requires us to manually identify the differences and rewrite the affected API documentations.
It was almost impossible for us to maintain copies of the documentation that were in circulation and keeping them up to date
Our goal is to develop a new approach that allows us to support multiple client-specific API documentation but at the same time, increase efficiency and scalability by automating the propagation of API changes.
The most effective solution to this issue is to document our API on a higher level of abstraction where we do not need to maintain individual documentation but instead just one Single Source of Truth. We tackle this issue on two fronts: defining the Single Source of Truth and generating multiple client-specific API documentation from it.
The Single Source of Truth, henceforth known as the Master Blueprint API documentation, defines every single Xfers API endpoints and its respective parameters. The definition is written to adhere to the Open API Specification (OAS) format.
This blueprint is not accessible to the customers, as it contains many endpoints that are not suitable for their use case. Instead, customers will only be presented with relevant API documentation that is generated based on Xfer’s client-specific configuration defined in a YAML file.
This is done by having a parser to iterate through the specific endpoints stated in the client YAML configuration and cherry-picking the relevant endpoint from the Master Blueprint that is to be included in the client’s copy of the API documentation.
Internally, this approach removed laborious manual creation, maintenance and update of multiple API documents, which resulted in greater efficiency and time-savings. Maintenance only needs to be done to a single master blueprint and the information on the other documentation will be automatically updated. Engineers will only need to define the OAS configuration for a new client and the API documentation is created quickly by pulling the relevant information from the master blueprint.
Scaling the display layer
Most companies use Postman to document their API, as it has an intuitive graphic interface for users to define their API, can generate request and response example, and provides a platform to host the documentation.
Compared to the complexity of OAS, postman is fast and easy to use, and is a great choice for small-medium tech companies. However, issues arise when these companies want to scale up their operations. It does not provide the versatility and scalability that big companies need for their API documentation. They do not have the option to choose their preferred graphic interface to render the documentation, cannot customise the documentation to their own liking or host the documentation on their preferred platform.
One of the deciding factors on why we migrated to OAS is to leverage on the industry standard for API documentation. It is backed by OpenAPI initiative and adopted by countless tech giants such as Google and Paypal. New packages and gems are constantly created making the API documentation highly versatile.
OAS provides the user with an option to choose from multiple tools to document their API. As the OAS definition is defined in a standard JSON or YAML format, developers are able to utilise this format to develop tools that generate documentation from a single file.
There are numerous documenting tools such as Redoc, Readme and Swagger-UI that generate the documentation from a single file. This will not only allow us to have a wide variety of packages to choose from, but also provide us with the modularity to render multiple client-specific API documentation on the same website.
Two ways syncing between code and API documentation
Due to the wide support for OAS, there are gems available that help to provide us with an avenue to document our API on an even higher level of abstraction.
For the next version of Xfers API, it will be defined using a RoR Grape gem which would allow us to utilize grape-swagger to generate OAS definition from our codebase. This removes the whole process of maintaining any API documentation as the documentation will be updated from our code-base. We will be able to reach our end goal where the Single Source of Truth is based on our codebase.
Xfer API Documentation Showcase
If you’re interested to view our new API documentation where our API endpoints are defined using the OAS and the client-specific documentation is automatically generated by our parser, please visit https://docs.xfers.io for the API documentation page and https://github.com/Xfers/oas-api-docs for the repository.
If you have any suggestions or comments, feel free to leave a note down below.
