Moonwalk 2024

[earth2marsh]

TL;DR Sets the goal to ship v4 of the OpenAPI Specification by the end of 2024 and offers guiding principles to help organize the work.

Over a year has passed since the next major version of OpenAPI (v4) was proposed. Its codename is Moonwalk, and it began with a simple post about what might be possible.

Since then, it has evolved, thanks especially to the spirited discussions in weekly Technical Developer Community calls. Topics have included modularity, security, references, parameter dependencies, RPC-style APIs, and more.

Such a passionate group of people could continue to discuss and debate the relative merits of changes indefinitely. However, if we are going to get serious about shipping v4, this is a great time to step back and reassess.

Major versions offer the rare opportunity to rethink fundamental assumptions. This can sometimes get overwhelming, so to help establish a framework for prioritizing and scoping the work for Moonwalk, we'd like to propose the following principles. These were chosen after reviewing the major proposals and discussions of the last year, and their order (semantics, signatures, inclusion, organization, upgrading, and naming) is intentional:

1. 🌖 Semantics provide purpose. It is not sufficient to describe the mechanics of an API without also describing its semantics, whether the consumer is a human or an AI. Semantics join the what (… does this do?) and the why (… does this matter?) to the how (… does this work?).

   OpenAPI has helped people build better APIs faster, and the ecosystem of tooling continues to deliver more value year after year. What is new today in 2023 is the rise of a new kind of API consumer—generative AI. LLMs can process OpenAPI descriptions and then use that API to solve problems. With generative AI’s ability to understand natural language, OpenAPI can help bring the power of APIs to non-developers with a level of accessibility never seen before. To fully realize this potential, API producers should decorate their mechanical descriptions of HTTPs requests with details that convey the meaning and purpose of those API operations. This, in turn, helps both people and LLMs to achieve better results.
   
   To say this another way, people have been using squishy, natural language to talk to each other for centuries, and we've used crunchy, programming languages to talk to machines for decades. LLMs bridge the squishy and the crunchy worlds, which means that a huge number of people can use APIs who could not before.
   
   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.

2. 🌒 Signature please! An API represents a set of functions, each of which describes a client-oriented purpose. A function is identifiable by its signature, which correlates to a set of HTTP interactions. Moonwalk places this concept at its center.

   Any HTTP API is always a means to some end. API consumers prefer to reuse existing functionality, and ideally they can learn about that functionality in terms that are most natural to them. 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. Past efforts in OpenAPI have focused on enabling developers to describe HTTP APIs. This reprioritizes them so that developers can use OpenAPI to define API functions with unique signatures that then map each signature to HTTP mechanics.

3. 🌕 Inclusion needs a big tent: Moonwalk aspires to describe all HTTP-based APIs. While it remains neutral on the design aspects of HTTP APIs, it recognizes the importance of having different design styles and opinions.

   Moonwalk should be able to describe the HTTP APIs that developers may already have as well as to design the APIs they may want to build. It should be able to accurately map the signature of an API function to an actual instance of an HTTP request and response provided by the API. 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.

4. 🌗 Organization through separation of 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.

   To support the growing customer base with diverse needs, the feature count will undoubtedly grow, introducing more complexity. To counterbalance this, we will apply more rigor to the modularization of different aspects of the API description. We will strive to eliminate ambiguity where it currently exists and leverage existing standards to minimize unnecessary novelty. Our goal is to provide a better experience for API description consumers, authors, and tooling providers.

5. 🌑 Mechanical upgrading. An important principle of OpenAPI v3 was that it offered a direct upgrade path from v2. Moonwalk carries this forward, which means that it must again be possible to mechanically upgrade to Moonwalk from v3 (and by extension, v2).

6. 🌔 Names have mojo. Over the last year, the rise of OpenAI has made it clumsier to talk about OpenAPI (especially when they intersect). We are on the brink of launching a second specification under the OpenAPI banner for API Workflows. Have you noticed that it is more fun to say Moonwalk than to say OpenAPI? So why stop?
   
   From this point forward, Moonwalk graduates from being just a codename to being the actual name of v4 of the API description specification. This brings back our mojo and restores a little swagger to our step.

--

The above is presented as a draft of an upcoming blog post. The idea behind this was to take the outside-in view in order to explain why Moonwalk should be interesting to the rest of the world. At this week's TDC call (Thu, Nov 30th), we plan to walk through the concepts above in hopes of learning how close (or far) from consensus we may be.

Thanks, Darrel & Marsh

[lornajane]

All good, but I am not sure about going big with the branding right now. If we could refer to it as OpenAPI 4.0 and maybe "project moonwalk", I think that would help people outside the immediate group to understand what it is all about.

[SensibleWood]

I agree. Words get latched onto easily and if "Moonwalk" turns out to be "not Moonwalk" then we are landed with an association we don't necessarily want in the future

[kevin-postman]

I too think keeping it OpenAPI v4 and project Moonwalk makes more sense. It's been a long process trying to get people to stop using Swagger as many have said, but I find many people use OpenAPI now and not Swagger. The idea of telling them to start using Moonwalk scares me. I'd rather see it used as it has been so far, a project name related to OpenAPI v4.

[kristenwomack]

+1 on OpenAPI v4 and project Moonwalk to avoid the fka OpenAPI, and also fka Swagger. Maybe we check balance on how many trees have been planted from saying Swagger as an input. ;-) Really like the semantics improvements and the mechanical upgrade aspects.

[rafalkrupinski]

It's been a long process trying to get people to stop using Swagger

Is that past perfect tense? You not implying people have stooped it, are you.

[earth2marsh]

Thanks for the comments here and the discussion on Thursday with the TDC. Based on feedback, the post draft has been updated and published. (One notable change was dropping the branding question, as that requires outreach/marketing group input!)

[rafalkrupinski]

Semantics provide purpose

Does it mean anything else than more description fields?

Mechanical upgrading

Since it's impossible to translate JSON Schema (in non-trivial cases) to a type declaration in any language, does it mean we're stuck with it? :/

Have you noticed that it is more fun to say Moonwalk than to say OpenAPI?

Not really

If there's anything wrong with OpenAPI, how about going back to Swagger? It's still a recognised name.