There are few projects in the API space with as dedicated a following as the OpenAPI Initiative (OAI) — and for a good reason! As a specification, OpenAPI has opened the door for a standardized API definition solution that makes for better portability and extensibility, more effective lifecycle management, and better developer experience across the board.

One of the most exciting parts about OpenAPI is looking to the future to see what it will become. This was made much more exciting with an announcement in early December 2023: OpenAPI has targeted the launch of v4, codenamed “Moonwalk”, by the end of 2024!

There is a lot of buzz about just what v4 will look like. Yet, there are multiple open questions. For instance, how OpenAPI will work with AI and LLMs seems to be a big one. Below, we’re going to take a brief look into this topic and consult with some experts to get their thoughts.

What Will OpenAPI v4 Look Like?

Before we dive into the guiding principles behind this new development, we should first get an idea of what it might look like.

Where is v4 Going?

First and foremost, v4 looks like it will be a huge update. v4 is poised to contain many features and has been designed to be a huge leap forward in form and function while unlocking new development and extension.

Darrel Miller, API Architect at Microsoft and Member of the OAI Technical Steering Committee, had this to say about the update:

“I think we have learned a tremendous [amount] about how people use OpenAPI in the last six years since the release of 3.0. I believe we can address the really significant outstanding issues in v4 to prevent the need for another major update. I think beyond OAS, we have lots of complementary efforts that need attention: workflows, overlays, APIs.json, SLAs, industry standards, etc.”

One huge aspect of v4’s development is that it is heavily informed by its user base and background. Development at this level of maturity really benefits from an incredible amount of awareness of the user base and the use case of the system. OAI has taken this to heart and is clearly thinking in terms of what the users of 2024 want in a 2024 product.

Marsh Gardiner, OAI Technical Steering Committee member and former Group Product Manager at Google, noted that the consumption model and expectations of OpenAPI are different now and require support and understanding. “What’s different today than a year ago is that LLMs have made it much easier for people who aren’t developers to use APIs,” he said. “In some ways, this is similar to low/no-code tools, but now it has potential to reach a much larger scale.”

AI, in particular, was in Miller’s mind as well. “We are committed to making OpenAPI better for AI-driven API consumers,” he said. “This is a fast-moving field that is new territory for many in the OpenAPI community. We are going to need to learn fast and find solutions that will be able to evolve as quickly as the AI community.”

Exciting New Features

With such a focus on providing new tooling and paradigms for the consumer, it’s no surprise that v4 comes with some exciting new features. One such feature is the adoption of imports as a replacement for $refs. This is a pretty significant shift — the $refs system, as it currently exists, forces location-based referencing, which ultimately limits the way the underlying code can interact. This, in turn, adds complexity to the codebase and introduces additional steps in the process of getting from idea to execution.

Darrel Miller notes that this is not just a small change – this is, in fact, a fundamental one. “Location-based referencing has been holding us back for too long,” he said. “It is a pain for tooling vendors to implement well, and it often forces consumers to do preprocessing to inline documents.”

Architect and developer Chris Wood adds that this complexity has been a problem in past versions and expressed a desire to see this improvement within the standard:

“The version 3.x years have largely been about building a presence outside the Swagger legacy and making the standard the best means it can be to represent an HTTP API. The next steps need to be about usability, and answering the question: How can I make my API description complete while also making it easy for consumers to understand and digest? The current specification leans in many ways to JSON Schema to service complexity, where the team behind Moonwalk should look to address areas of complexity directly in the standard.”

This approach to making the standard more human and usable can also be seen in the new focus on signatures. Gardiner notes:

“[I’m very excited about] the focus on signatures, as that is what organizes the spec into human-oriented functionality. It suggests that eventually, it should be possible to identify any actual API request back to the function described in an OpenAPI document.”

It’s clear that v4 is meant to be a broad-use and applicable technology for various systems, use cases, and functions in a way that v3 and before did not achieve. With more human-friendly paradigms, v4 is poised to be a significant shift in how OpenAPI is utilized in the developer’s day-to-day.

Major Roadblocks

Of course, with any new (or updated) solution, there will be some roadblocks. One of the biggest issues with the OpenAPI approach arises from one of its biggest benefits – it’s an open standard. While this delivers many benefits, it also introduces some timing and effort issues due to the fact that everyone involved is not necessarily focusing solely on this development process.

“This is a volunteer effort, and everyone involved has day jobs that keep them busy,” said Miller. “Finding time to contribute to a process that can often devolve into debating the minutiae of HTTP API edge cases requires extreme patience and commitment.”

Marsh echoed this, explaining that “open source standards take time to evolve.” The fact is, however, that everyone involved is pulling in the same direction, and some of the early development documentation that’s been released has been quite exciting. As of today, one of the best pieces of information we have about the development process has come directly from OpenAPI’s announcement concerning Moonwalk, and in it, we can see some incredible guiding principles.

The Guiding Principles Behind the Moonwalk

In the blog post, OpenAPI noted that there are some strong guiding principles behind this development. As a result of their proposal review and some in-depth discussions, they fell on five main principles – semantics, signatures, inclusion, organization, and upgrading.

Semantics

The first of these principles is a big one – semantics. According to OpenAPI, “semantics provide purpose” and are the critical element of defining an API and how it does what it does. To this end, it seems that a lot of the new development will focus heavily on allowing developers to provide more context and semantics to end users, allowing for more detail-oriented context and clarity.

OpenAPI clearly notes that people use natural language, a form of language they label as “squishy,” to speak with one another. Machines, on the other hand, use “crunchy” language. LLMs, thus, are halfway between “squishy” and “crunchy”, connecting people and APIs in a way that may not have been possible several years ago.

This is a great effort on OpenAPIs part. The way of interacting with systems in the future is going to have fewer and fewer technical requirements, and being able to provide this context in a way that is consumable and semantic will lead to better outcomes overall. OpenAPI notes that this is going to occur with or without them, and as such, they want to own the process:

“Regardless of your opinion of generative AI, from over-hyped to world-changing, we can expect that many people will be using OpenAPI to drive AI-based API consumers. If OpenAPI does not step up to address the needs of that community, they will find alternatives.”

Signature

By OpenAPI’s estimations, an API fundamentally describes client-oriented purpose through its functions, and these functions are defined as a “signature” or a set of HTTP interactions. Moonwalk is centering this concept and making the actual client logic more obvious and important. API consumers, in this definition, want to know why something occurs much more than the technical methodologies of how it occurs. As such, this signature of purpose needs to be more prioritized.

By OpenAPI’s own admission, this is nothing something that is adequately done in the current release:

“That a PUT/PATCH/DELETE returns a 200 or a 204 is an implementation detail that pales in comparison to the function it performs for the client. Today, there are limited ways to express the signature of an API function in OpenAPI. A pathItem can’t use query parameters to distinguish operations. There can only be one operation per HTTP method. These are artificial constraints on the signature of the API functions due to the lack of a formal definition of the unique signature.”

OpenAPI wants to fundamentally change this, allowing developers the ability to communicate to the end user exactly what is happening with a clear link to the mechanics of how it is happening. This should provide much greater clarity for the end user and a higher level of understanding across the board.

Inclusion

The OpenAPI Initiative’s blog post makes a very bold statement here: “Moonwalk aspires to describe all HTTP-based APIs.”

This is a big ask of any solution, but it’s a necessary one. It often feels like there are as many paradigms and approaches to API design as there are APIs, and too often, it feels like solutions have a “favorite” that is easier to document and pull into a specification. OpenAPI notes that, even if this bias exists, it should come with solutions to circumvent it:

“Moonwalk does prefer resource-oriented API styles due to their overwhelming popularity, but it should be possible to describe purely RPC APIs, even when those API signatures are distinguished via HTTP header values or request body values.”

In essence, Moonwalk is aiming to be a home for all sorts of APIs, both those that exist and those that are being designed. This “big-tent” approach is huge and could be a game-changer in this space.

Organization

Organization is often something difficult to communicate in a specification. Technical documents are already quite heavy, and when looking at an API and a collection of definitions or specifications, this can only be exacerbated at scale. OpenAPI wants to enable organization by separating concerns:

“For example, the changing shape of an API should move independently of API deployments. API deployments may be secured with different security schemes. API functions’ signatures should not be tightly coupled to content schema formats.”

While many would respond that this would only cause an increase in features and complexity, OpenAPI notes that, to balance this, more rigor needs to be applied to API descriptions and modularization therein. Focusing on clarity and removing ambiguity requires organization, and by engaging in this sort of improvement, the consumer, author, developer, and end-user experience should likewise be improved.

Upgrading

OpenAPI notes that upgrading is a continual concert with any new product version. They note that OpenAPI v3 was offered as a direct upgrade path from v2, and they’ve clarified that v4 will do this in the same way — it will be possible to mechanically upgrade from v3 to v4, and by extension, from v2 to v4.

Conclusion

There’s a lot to love about this announcement. While the devil’s in the details, OpenAPI has proven itself time and time again as a collective of people who know what they are doing. If they can execute v4 in this way, they are poised to release a revolutionary version of this product that could make the lives and efforts of many developers that much easier.

Lastly, if you’re interested in this effort, this is not something you have to just stand on the sidelines and watch. According to Gardiner, the developer community around OpenAPI is pretty welcoming if people want to get involved. “OpenAPI is built around the passions of many people building something they believe in,” he said. “If you’ve been inspired to join the effort, reach out!”

What do you think about Moonwalk? Are you as excited as we are? Let us know in the comments below!