Since the days of yore, long before Roy Fielding’s dissertation on REST and around the time the words ‘strategic alignment’ were first uttered in public, an enterprise architect asked the question: Do we build, or do we buy our software? This question is a classic piece of the IT puzzle, a never-ending search for enlightenment to ensure that an organization spends its money wisely by making the right choice in sourcing software tools.

Roll forward about a thousand years, and we still ask that question in the context of the API economy, especially for OpenAPI. OpenAPI is supported by a huge variety of tools and platforms across the API lifecycle, with those tools and platforms providing different functions and fulfilling many purposes.

However, the broad OpenAPI ecosystem isn’t always easy for enterprise architects (or anyone looking for OpenAPI tools). Before starting your search for OpenAPI tools, or going ahead and building them, you need to ask yourself what your goals are so you can answer the build vs. buy question successfully.

The Experience of Building OpenAPI Tools

Building your own OpenAPI tools, or creating them for others to consume, is a path many developers have taken. The tooling ecosystem is vast. As the OpenAPI Initiative tooling website shows, there are innumerable tools of many different types, with a great number of commercial solutions available as well, to support organizations in their efforts as both API providers and API consumers. However, an out-of-the-box tool does not always meet organizational needs, for many reasons.

Our 2024 Austin Summit was notable for many reasons, including a talk on this subject by Adam Leventhal. Leventhal is from Oxide Computer Company and presented his experiences of building OpenAPI tools from scratch. Oxide leverages OpenAPI for their private cloud in-a-box solution, where they favored a Rust-based, code-first approach to creating their API layer and with it OpenAPI descriptions for their platform.

Oxide’s experience with the OpenAPI tooling ecosystem was, by Leventhal’s account, not great. One requirement Oxide had was to generate clients based on the OpenAPI descriptions generated from their Dropshot tool. Existing OpenAPI tools for Rust simply did not provide what Oxide needed, so they set about building a home-grown tool, Progenitor. Progenitor is a Rust crate that generates an API client based on an OpenAPI description, and is an important part of how Oxide supports their platforms.

Encountering Friction With OpenAPI

Leventhal’s talk described the challenges Oxide encountered with OpenAPI. Leventhal’s experience was that OpenAPI is a broad specification, which caters to many edge cases. “There are eight different ways of saying the same thing,” he said. This flexibility means there are many design choices, and finding the right one is not always straightforward.

Furthemore, the goal of implementing a code-first approach to master the shape of the API in code meant that many edge cases needed to be ignored. “We were trying to be inflexible,” said Leventhal, “doing it one particular way.” He was clear that building a tool that leverages OpenAPI has to be geared to a use case or problem statement. “You don’t need to solve the general problem, you need to solve your problem,” said Leventhal. This singularity of purpose may not suit tooling makers who cover a wide range of use cases, but it is vital for organizations that have a clear need to implement tools that they build themselves.

The Path Forward: Building an OpenAPI Tool

Leventhal’s conclusions suggest that building Progenitor with OpenAPI support was the correct course of action: “OpenAPI was right…even though the ecosystem wasn’t what we had hoped it would be.” This conclusion provides a valuable insight into the value of using OpenAPI, namely: The ecosystem is enormous and your developer community will undoubtedly find the tools they need to help them consume your APIs. That is not, however, always a guarantee. Reasons that you might need to build your own OpenAPI tools include:

• Specific use cases: The Oxide use case was specific and the quality they needed from a code generator was significant. A use case off the beaten track gives more weight to the argument for building OpenAPI tools.
• Version support: Tooling makers evolve their tools at their own cadence. There may be a significant lag between a new version of OpenAPI being available and support becoming available in a given tool. For example, there are many tools in the ecosystem that have not adopted version 3.1 yet, and some significant vendors, such as the Google Cloud Endpoints solution, stuck with version 2.0 (Swagger). Building your own OpenAPI tools puts you in charge of your destiny in this respect.
• Ownership: There may also be reasons why you want to build your solution because it forms a significant part of your intellectual property. If your OpenAPI tool is an important part of your software stack and a significant reason for how you make money, you need as much control as possible. In this context, building your tools makes sense.

These reasons are not specific to OpenAPI. Use cases, programming languages, operating environments, and industry regulations can all result in the need to build your tools in any technology. However, the reasons for creating your OpenAPI tools do not apply across the board.

The Arguments for Buying Your OpenAPI Tools

There are many reasons why you would either buy your OpenAPI tools or use freely-available open-source tools. In Oxide’s case, this was clearly not an option, as support for the Rust programming language and code generation was not good enough for their needs. However, the Oxide use case is one that most software developers simply do not have. We do not build machines from scratch, nor develop operating systems and management planes for hardware systems. Many of us have simple use cases, like publishing documentation.

The key here is that OpenAPI tools are often coupled with “something else,” to do a specific job or task. The documentation use case is an obvious example, but API design (when not doing code-first) across a team is another. Commercial tools like Postman Enterprise, SwaggerHub, and Redoc Workflows offer collaboration and automation features that build on OpenAPI compatibility to offer users a unified design experience.

The buy argument here is significant. Your organization is very unlikely to invest the time and money in creating a design tool with a collaboration feature when they can just lift one off the shelf. The main caveat is, of course, the same one that Leventhal pointed out: OpenAPI is very broad, and there may be a feature critical to your needs that is missing. Sourcing products compatible with OpenAPI is therefore like any purchasing decision, in that you must do your due diligence before buying by understanding your needs.

A Use Case View of OpenAPI

The build vs. buy debate for OpenAPI tools is not a straightforward slam dunk for many API professionals looking for something to help accelerate their efforts in providing or consuming APIs. As Leventhal’s experience shows, starting from scratch and ensuring you have done everything you need to do is difficult, as is trying to be “feature complete.” There is also the question of whether tools need to implement everything because in many cases the functionality that marks the tool as being feature-complete is not used by the developer community.

The proposed refactoring coming in version 4 of OpenAPI will help make sections of the specification more modular and, therefore, easier to ignore if irrelevant for some tools. However, there still needs to be easier answers to the question of what needs to be implemented for a given use case. One possible solution that the OpenAPI Initiative could help with is creating tooling “profiles,” which describe features that are important to a well-defined use case.

For example, consider the Tag Object. The guidance in the specification talks about “additional metadata” being provided through a Tag, but most implementers leverage tags for navigation when providing documentation tools. Improving the specification would help clarify usage, as reflected in the current Moonwalk discussion on this topic, but also providing a use case view that describes using tags for documentation would be of enormous value as well.

This use case view may well prove very useful to the wider OpenAPI community. As the OpenAPI Initiative moves from a single specification community to a multi-specification community, with the publication of Overlay and Arazzo, finding a way to provide insights like this will be extremely valuable in its future development.

Build vs. Buy OpenAPI Tools

Going back to the original question of whether to build or buy OpenAPI tooling, the answer is: It depends. We’ve described clear reasons why building your own tools is a good idea, but you should be prepared for the inherent complexity of a standard that attempts to represent a variety of different internet standards.

The “hidden” complexity of OpenAPI is especially important if you are looking to build a commercial product where users might demand features considered edge cases in the OpenAPI Specification. Many of us will be satisfied, however, with what we can get from the tooling community. The huge number of tools, many of which are very mature and cover OpenAPI features well, will provide what we need to be successful in our efforts to build and consume APIs.