Open API Specifications: Improving Documentation & Communication

At Remote, enhancing our application programming interface (API) design and definitions was a key strategy for making our platform more accessible to developer communities worldwide. 

Our dedicated efforts culminated in the launch of the Remote API. This allows HR and payroll companies to tap into our extensive global infrastructure, making it easier than ever to expand their teams across borders.

In this article, we delve into our journey, from built-in documentation to the adoption of OpenAPI schemas. Learn all about why this shift was essential for our platform and the significant benefits OpenAPI offers, especially for projects that use Elixir.

The evolution of API specifications in Remote’s platform

As Remote’s platform evolves, so do our API specifications. This evolution is critical to supporting the growth and diversity of our development team.

The importance of internal APIs

Improving the developer experience is key in today’s API landscape. At Remote, our platform consists of various domains, each demanding unique tech solutions. Our internal APIs play a crucial role here, making it easier for our developers to work together and communicate smoothly.

As our team grows each month, these APIs are what connect different skill areas. They give our team a good grasp of our services' capabilities without needing to dive into the source code.

Remote's domains include areas like user interface design, data management, and security features, all managed by devs with the skills needed for that domain. Our internal APIs link these domains with a common langauge. This means efficient development across the platform, regardless of the programming languages, tools and software our developers use.

These APIs are key to bringing together the efforts of our diverse team and maintaining the integrity of our platform. And they're the reason we keep delivering top-notch solutions globally.

By focusing on strong internal APIs, we're making our development cycle smoother and more effective. This is a big part of how we're growing our platform.

The role of API definitions and documentation

OpenAPI combines clear specifications and definitions along with easy-to-understand documentation from development to integration:

• API specifications: Think of these as the architecture of API. They outline the technical aspects, like how the API works, its endpoints, its data formats, and its security mechanisms and protocols.

• API definitions: Definitions go into more detail than specifications. They describe specific parts of an API, like the data structures, parameters, and error types, providing a common understanding and clear reference for developers.

• API documentation: Documentation is akin to a user manual for an API, detailing how to use and integrate it. It includes code examples or code snippets, usage scenarios, and troubleshooting tips for making APIs user-friendly, especially for external developers.

This approach simplifies the entire API lifecycle, making OpenAPI a solid choice for our global platform.

Types of API specifications

API specifications are sets of rules that define how the API functions and interacts with software and client applications. Here’s a brief overview of the most common types:

• Representational State Transfer (REST): A popular choice due to their simplicity, REST APIs are used widely in web services. 

• Simple Object Access Protocol (SOAP): Preferred for enterprise-level services where security is a priority.

• GraphQL: Ideal for complex systems with large amounts of data.

• Remote Procedure Call (RPC): Focused on speed and is particularly useful for smaller, faster operations.

Each API specification serves a different purpose, and the choice depends on the application’s needs. 

For instance, the need for a clearer, more adaptable, and more developer-friendly specification well-suited for its global platform drove Remote’s shift to OpenAPI.

Migrating to OpenAPI specifications

Remote’s shift to OpenAPI for our internal RESTful APIs came after a detailed review through our Request for Comments (RFC) process. This process involved evaluating our API documentation needs and considering various API specifications.

Ultimately, OpenAPI was selected due to its usability and compatibility with the Elixir ecosystem. It stands out for its easy-to-use documentation generation tools, as well as its client code, server generation, and data validation functionalities. These features make it a versatile choice for our expanding platform.

Not only that, but OpenAPI offers a more flexible and developer-friendly environment than other specifications, like REST, SOAP, and GraphQL. It aligns perfectly with Remote’s goal of efficient and transparent API management.

Overcoming documentation challenges

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 search for a better solution.

The limitations of built-in documentation

As Remote’s platform expanded, the limitations of our built-in documentation became increasingly clear — a common scenario for fast-growing teams. 

Here's a breakdown of the key issues we faced:

1. Maintaining example JSON responses and query parameters: Our process involved manually updating JSON responses and query parameters within ‘@doc’ attributes. Not only was this time-consuming, but it was also prone to errors and inconsistencies.

2. Keeping documentation up-to-date: The dynamic nature of our APIs meant frequent changes were needed. However, our built-in documentation system relied on the team remembering to update it manually. This often led to outdated or inaccurate documentation, causing confusion and inefficiencies.

3. Accessing and navigating the documentation: The built-in system required extra steps to build and browse the documentation. Additionally, some of our developers were less familiar with Elixir’s tooling, making it harder for them to access the information they needed.

These challenges highlight the needs that drove our shift to OpenAPI. And we’re pleased to report that this change has significantly improved accessibility and productivity, particularly for our globally distributed team.

Challenges in migrating to OpenAPI

Remote faced a few hurdles in switching to OpenAPI. The main challenge was adapting our APIs to OpenAPI’s format, which required significant code updates. This was a substantial task for our developers, especially considering OpenAPI is based on an API-first design principle.

Training was another issue. Our team needed to learn OpenAPI quickly — a challenge for those unfamiliar with the framework. We tackled this with focused training and helpful internal resources.

We also dealt with integration challenges and ensured that our old and new APIs worked well together. This was managed through a step-by-step integration process that allowed for meticulous testing and troubleshooting.

Despite these obstacles, moving to OpenAPI was beneficial for Remote. It’s improved our documentation, streamlined development, and enhanced collaboration.

Understanding OpenAPI

OpenAPI has become a pivotal part of Remote’s API strategy, offering a robust framework for API development.

Basics of OpenAPI specifications

OpenAPI is a way to describe RESTful APIs in a standard format that's easy for both people and computers to understand. Your API definition file can be written in YAML or JSON. Here’s a quick look at its structure:

• Paths: These are the endpoints or URLs for API operations, each of which is linked to specific functions.

• Operations: GET, POST, and PUT describe the actions that are possible at each endpoint.

• Parameters and responses: You specify input parameters and expected outputs for each operation, detailing data types and response formats.

This setup helps clearly outline an API’s functions, making integration and teamwork smoother. For Remote, using OpenAPI has greatly improved our API’s functionality and ease of use.

OpenAPI in Elixir-land

In integrating OpenAPI into our Elixir-based development at Remote, we used OpenAPI Spex, an Elixir library. This tool streamlines creating and serving OpenAPI specs from our code, making the process more efficient and well-integrated with our usual workflow.

Our specifications follow the structure of the Phoenix application, ensuring consistency in our API development. Using OpenAPI Spex has improved the clarity of our API documentation and the overall developer experience, making teamwork smoother.

This method highlights OpenAPI’s adaptability across different programming environments, showcasing its role in modern API development.

Implementing OpenAPI at Remote

The transition to OpenAPI at Remote was a well-planned and phased process that took us from the design stage to development.

Our implementation strategy

Adopting OpenAPI at Remote was a carefully managed, one-step-at-a-time process. We began with two controllers covering six operations and created both the specs and developer guides via OpenAPI Spex.

We added OpenAPI specifications progressively, updating them as needed with each new API functionality. This method avoided disruptions to our existing workflows and allowed for a smooth transition. We sometimes used placeholder specs initially, which we detailed more over time.

This gradual implementation allowed our team to adjust to OpenAPI comfortably. It also allowed us to refine our use of its features, ensuring they fit well within our Elixir environment. This careful approach has significantly improved our API’s efficiency and usability.

5 benefits of switching to OpenAPI specifications

Shifting to OpenAPI at Remote has brought about several key advantages:

1. Easier documentation navigation: OpenAPI makes our API documentation clearer and more accessible while supporting a better async workflow. This leads to fewer misunderstandings and a smoother workflow for our team.

2. Better testing capabilities: With OpenAPI, we can reliably test our API specifications. In doing so, we ensure our documentation remains up-to-date and bug-free.

3. Automated mock data for frontend development: OpenAPI’s ability to generate mock data automatically speeds up our development, reducing manual tasks and helping us focus on more complex challenges.

4. A unified source of truth for documentation: Establishing a single, definitive source for our API documentation greatly improves our developer experience, leading to fewer errors and faster delivery times

5. Scalability for team growth: As our team grows, OpenAPI's scalability makes it easier for new developers to get up to speed.

These benefits not only streamline our internal processes but also enhance the overall efficiency and quality of our platform, reinforcing our decision to adopt OpenAPI.

Open API means more transparency for Remote

Switching to OpenAPI reflects Remote’s commitment to transparency, a key value in our remote-first approach. This move from built-in documentation to OpenAPI has improved process automation, documentation clarity, and scalability. These things are crucial for sustainable growth in remote settings.

OpenAPI isn’t just beneficial for our Elixir projects, though. It’s also valuable for our partners and clients. 

If you’re interested in OpenAPI and its capabilities, we encourage you to request access or explore further with our developer documentation and other resources. And if you’re one of our customers, discover how integrating with the Remote API can enhance your business.