OpenAPI: How to Handle File Management

OpenAPI is a human- and machine-friendly API description format for HTTP APIs, and is seeing increased adoption across the software industry. As organizations work on the API experience for themselves as producers, and as consumers of an increasing number of third-party APIs, it’s key to have a good process for working with OpenAPI files.

Design-First APIs

Design-first is emerging as an efficient and effective approach to building APIs. In design-first APIs, the OpenAPI description is updated to describe the proposed API changes. Documentation and mock servers may also be produced at this stage, while feedback is collected from stakeholders. Once the changes are approved and accepted, the API is implemented. Working in a design-first approach means that changes to API design are easy to achieve at an early stage, where only the OpenAPI description needs to be updated and no code has been written yet. The downside is that many organizations find the OpenAPI format difficult to work with; often the API description is a single file and it may run to hundreds of thousands of lines of YAML or JSON. While having a good editor with OpenAPI support really helps, the structure of the OpenAPI description itself can also make a big difference to your API authoring experience.

Use OpenAPI $ref Syntax

One reason the files get so long is that the OpenAPI format is, by necessity, verbose and because the same elements are often repeated in multiple places. For example, a newsletter microservice probably has an email field and a list of subscriptions that are the same in more than one endpoint. OpenAPI makes this repetition easy with its `$ref` syntax. Define the field once in the `components` section of the OpenAPI description and then refer to it with `$ref` in every location where it is needed. Here’s a snippet of the newsletter microservice example: Using `$ref` not only makes the files more manageable but also encourages consistency by using the same schema definitions throughout an API description. Consistency is key for API experience and so the `$ref` syntax serves both producer and consumer when it is used. The `$ref` syntax can also refer to content in other files, which gives users more ways to make their OpenAPI files easier to work with.

Separate Components

Since OpenAPI 3.1 (released February 2021), an OpenAPI description can be valid with any one or more of `paths`, `webhooks` and `components` declared. What this means in practical terms is that if your API is purely webhooks or you have a single set of components that are used by multiple APIs, you can publish those API descriptions without needing an empty `paths: {}` object. Especially for microservices architectures, common components used to give a consistent experience across modules is a popular and helpful pattern. For example, for a shopping application that has separate “account” and “order” services, it might make sense to separate the components into one OpenAPI file, and refer to it from the individual API descriptions for the separate services. The directory structure would look something like this: If there’s a schema `customer_name` in the `components.openapi.yaml` OpenAPI file, the other API descriptions can refer to it with syntax like the example below: Each OpenAPI file is smaller, making it more manageable to edit and review changes. When you are ready to publish either the Account or Order API, you can bundle the file using a tool like Vacuum or Redocly CLI to create a single OpenAPI file that can be used to pass to another tool such as your documentation platform or API gateway.

Radical OpenAPI File Structures

Some organizations split up their OpenAPI files more thoroughly, holding one file per operation and another for each element in the `components` section. With the `$ref` syntax, really anything is possible! At its most radical, the newsletter example from earlier ends up looking something like this: Whether you design and build your API structure this way, or use a tool like Redocly CLI’s `split` command to restructure an existing API description, working with many smaller files has advantages:

• Each file is small enough to easily open and view
• You can view multiple files at once without losing your place in a long file.
• Proposed changes are much easier to review because you can see which areas are affected.

One major downside is that each file is “just” YAML, so there’s no OpenAPI file validation available when you’re working on the individual elements. Depending on your team, that might be an acceptable trade-off though, and the usual API linting and governance steps can be applied in CI to the bundled version of the API description.

What’s Your Goldilocks Granularity?

There is no “right” answer for how to structure your OpenAPI files. Some teams are very happy with a single file and see no problem to solve. Others are fully committed to a very granular approach and wouldn’t consider changing. The right answer for your team might lie somewhere between the extremes, but by being aware of the options and open to change, you can find an approach that fits your needs and leads to more efficient and happier API experiences.