Open API Specifications: Improving Documentation & Communication

The Remote team has been working hard to deliver the launch of our Remote API, designed to help HR and payroll companies leverage Remote’s powerful global infrastructure to help more businesses hire globally. By taking the international infrastructure that has allowed us to offer a superior experience for businesses and teams around the world and making it available to developers, we’re able to afford so many more businesses the chance to expand their global team.

In this article, we want to focus on the journey we took to migrate from built-in documentation to using OpenAPI schemas. You will learn why this was so important, and we’ll explain the benefits of using OpenAPI for your Elixir projects.

Why are internal APIs so important?

A large number of developers are working on the Remote platform, and our team continues to grow every month.

There are many different domains within the product, and different developers have different specialties, both for the domains and for the backend and frontend technologies powering them. This makes our internal APIs essential for effective communication.

We started by using Elixir's built-in documentation features to document our APIs. This served us well for a while. However, as our team grew, we needed more. A collection of issues began to surface that triggered our need for a better solution

The problems with relying on built-in documentation became more obvious, and they are familiar challenges for any team experiencing fast growth:

• Maintaining example json responses, query parameters, and request bodies in @doc attributes: This involved copy/pasting json and keeping a list of query parameters.

• Ensuring the documentation was up-to-date: at times the docs would go stale and not match the API, because this system relied on the team remembering to update whenever a change was made.

• Exposing and browsing the documentation: including extra steps to build docs and opening and finding endpoints. Some developers are not as familiar with the Elixir tooling, another barrier to pass to get to the docs.

Thankfully, there is a better way to maintain API documentation. We want to explain how to simplify documentation management for a growing global team and reduce manual upkeep.

Remote's internal API specs

For introducing changes to the development process, we have an internal RFC (Request For Comments) process. In this case, we had two separate RFCs with some overlap around improving our API documentation. After some conversations, we opted to adopt OpenAPI specifications for our internal RESTful APIs.

OpenAPI is a specification for RESTful APIs. It's widely used and the Elixir ecosystem has good tooling for it. From the specification, you can then generate documentation. It has several other functions as well, like generating clients, servers, data validation, and more.

Intro to OpenAPI specifications

OpenAPI’s own introduction is quite comprehensive, but here's the TL;DR:

An OpenAPI specification can either be a yaml or json file.

• You need to define a “Path” for every API endpoint.

• Each Path can have multiple “Operations” (get, post, put, etc).

• Each operation describes the parameters, payload, and possible server responses.

OpenAPI in Elixir-land

To make adding and editing specs more integrated to our normal development flow, we decided to use Open API Spex. Open API Spex is a library for Elixir to generate and serve the Open API Spec document from code.

To organize our specs, we mirror the Context structure of the Phoenix app.

Implementation for Remote's team

The implementation of this has been intentionally gradual. The initial change started by writing specs for two controllers (six operations), with a bit of developer documentation on how to work with Open API Spex.

When working on functionality related to an endpoint, we add specs along the way. Sometimes, we add incomplete placeholder specs which we can later expand on.

What do these changes mean?

Although we are not done yet, we're up to around 150 documented endpoints. Already our team is experiencing some tangible benefits, with cleaner alignment and less manual work leading to speedier delivery on critical projects.

The biggest wins with our new API specs

1. Documentation is easy to find and browse, leading to less confusion about the APIs, fewer questions and a better async workflow.

2. We can test the specs! Now we can ensure our documentation is reliable and up to date, which ultimately reduces bugs.

3. We can provide mock data from the specs for the frontend, automatically. Less manual in this regard makes us faster as a collective.

4. We now have a single source of truth for API documentation!

This last result is such a win for our team and for Remote as a business.

The developer experience boost is significant. This new clear single source of truth makes it so much easier for our team to understand and deliver value. We are reducing the frustration involved in context shifting, which means less errors and faster delivery.

This solution is also more scalable, setting up our processes in the cleanest possible way for new starters - something of critical importance as the Remote team is growing so fast.

Open API means more transparency for Remote

More importantly, this move to migrate from built-in documentation to using OpenAPI schemas delivers on one our continual quest for Transparency; one of the fundamental values of Remote. To succeed in a Remote-first business, transparency is vital.

Automation, documentation, and scalable processes are the lifeblood of our company. Indeed, any team trying to facilitate sustainable fast growth in a remote environment, either in an engineering team, or any other department, can benefit from more transparent work practices. At the very least, we’re confident that using OpenAPI for your Elixir projects will serve you well for the future.

Ready to start the journey to becoming an API partner? Request access today to learn more and view our developer documents.If you're a Remote Customer and wondering how you can access the Remote API, check out the Remote API for Customers.