Skip to main content
Category

News

OpenAPI Moonwalk 2024

By Announcement, Blog, News

An astronaut plants a flag with an OpenAPI logo on the moon.What comes next for the OpenAPI Specification? How will v4 improve on the success of OpenAPI v3? What can the spec help solve problems in the context of AI and LLMs?

As 2023 comes to a close, answers to these questions are beginning to take shape. With an aggressive goal of launching v4 “Moonwalk” by the end of 2024, it is going to be an exciting year.

Because there is so much work to be done, it was necessary to establish some guiding principles. After reviewing the major proposals and discussions of the last year, these are semantics, signatures, inclusion, organization, upgrading, and their order is important:

    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 HTTP 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.

    1. 🌕 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.

    1. 🌗 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.

    1. 🌑 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).

Important open source projects like OpenAPI depend on contributions from many people. If you are as excited as we are about the ideas above or about the opportunity to leverage AI to help APIs be used by more people, then please get involved! A great way to start is to join our weekly calls on Thursdays (details), and anyone who wants to join is welcome!

 

Tools That Support OpenAPI Specification

By Blog, News

Over the last 18 months we’ve been looking at how we can better capture data on the OpenAPI ecosystem with particular focus on tooling – what tool makers are doing, what versions of OpenAPI they support and so on. Tooling registries obviously already exist in the wild such as openapi.tools. The goal was not replicate the functionality of these registries, but to industrialize the data collection process using a mechanism that was eminently extensible and could be expanded with very limited modification.

Introducing our OpenAPI tooling registry. The registry exposes a “classic” UI based registry hosted at https://tools.openapis.org that uses data automatically sourced from existing registries and uplifted with data collected from (as a first cut) the Github API. This mechanism was proven by Mike Ralphson and used to publish https://apis.guru/awesome-openapi3/, and we’ve taken the approach and applied it to all Github projects we’re sourcing. We also provide the raw data as a means for users to “slice-and-dice” in ways they see fit or ways we haven’t thought of yet.

The sourcing and consolidation of the source data is wrapped by a build process written in Node.js that runs on Github Actions and collects new data on a daily basis. The data collection process itself is not wedded to a given data source. In our source repository we implemented the concept of “processors” that are tailored to a given source and then normalize the data to the registry format. As part of this process different tools are categorized using a Bayesian approach then attempts to put tools into the right “bucket”.

The repository as it stands is really just a first cut. There is more work to be done, with a list of issues currently focused on improving data quality, creating better categories and providing the data in a variety of formats. There is also an opportunity to use this data for outreach to tooling users, using it as an engagement tool to encourage them to both describe their needs and advance their tooling to the latest version of OpenAPI. There is also an opportunity to bring tooling data together across specification languages – GraphQL, Async API, JSON Schema et al – to elicit a more holistic view of the API ecosystem and look at how cross-specification tooling might be of benefit.
As always feedback is welcome. If you have any suggestions for improvement please raise them on the repository or get in touch if you’d like to talk in more detail about any aspect of the implementation.


OpenAPI Resources

To learn more about participating in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor neutral description format. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

About Linux Foundation

Founded in 2000, the Linux Foundation is supported by more than 1,000 members and is the world’s leading home for collaboration on open source software, open standards, open data, and open hardware. Linux Foundation projects like Linux, Kubernetes, Node.js and more are considered critical to the development of the world’s most important infrastructure. Its development methodology leverages established best practices and addresses the needs of contributors, users and solution providers to create sustainable models for open collaboration. For more information, please visit us at linuxfoundation.org.

Developers: APIs are crucial to business, but tough to get right

By News

A survey of API developers claims security, customer satisfaction, and speed of deployment are among the biggest challenges
APIs matter, big time, and not offering an API deprives your software or service of a crucial audience. But it’s tough to get an API right because of unintegrated tooling, security issues, and the difficulty of iterating and resolving problems quickly.

These and other insights are part of the “State of API Survey Report 2016” issued this week by API testing and tooling company Smartbear. Assembled from surveys of more than 2,300 developers in 104 countries, the report looked at four major categories: technology and tools, development and delivery, quality and performance, and consumption and usage.

[Read the full article on InfoWorld here]

Developer.aero adopts new Open API Definition Format via 3Scale Platform

By News

We are delighted to be associated with the latest global API standards initiative which is being driven by a new organization, the OAI (Open API Initiative). This non profit organisation is aiming to create a new, more formal description format for Web APIs, provisionally called OADF (Open API Description Format).

The Initiative is hoping to create an open technical community within which members can easily contribute to building a vendor neutral, portable and open specification, which will extend the existing Swagger specification, for providing metadata for RESTful APIs.

The Developer.aero platform, which currently uses the Swagger specification, will adopt the new OADF specification going forward, and will automatically keep up to date with the new versions.

[Read the full article on developer.aero]

Interview with Tony Tam on the Open API Initiative and Latest Swagger News

By News

After the Linux Foundation announced the formation of the Open API Initiative (OAI) in the beginning of November with an impressive list of founding members, API developers had questions about the role OAI would play driving consensus around standards.

Tony Tam, founder of the Swagger project, addressed some of these questions later in November at the API Strategy and Practice Conference in Austin, Texas. InfoQ met Tony at the conference to get in-depth answers to questions we felt our readers would want to ask.

InfoQ: Can you tell us more about your new role at SmartBear and why you recently decided to join them?

[Read the full artilce on InfoQ]

Open Source Projects Further RESTful API-Based Development

By News

Open source projects are emerging to further software development practices based on RESTful APIs, which are becoming more instrumental in providing app back-end services and other functionality.

To establish standards and guidance for how REST APIs are described, SmartBear Software recently launched an open source project under governance of The Linux Foundation called the Open API Initiative(OAI). Meanwhile, other vendors are open sourcing their own homegrown API-based projects, as DreamFactory Software Inc. has done with its back-end for mobile, Web and Internet of Things (IoT) applications.

[Read full story at ADTMag]

IBM collaborates with Yes Bank, Bian to promote the API economy

By News

IBM (NYSE: IBM) today announced API Harmony an intelligent cloud-based API matchmaking technology for developers as part of a series of technology, product and services announcements to advance the growing API Economy.

API Harmony provides a unique developer experience, using cognitive technologies like machine learning and graph technology to anticipate what a developer will require to build new apps, make recommendations on which APIs to use, show API relationships, and identify what is missing.

The API Economy – a commercial exchange of business functions, capabilities, or competencies as services packaged in APIs – is the driving force behind much of the digital transformation across industries today, enabling business leaders to transform their organizations, build new ecosystems and monetize core assets, services and products. The API Economy is estimated to become a $2.2 Trillion market by 2018.1 According to IT Research and Advisory Firm Ovum, during the next two to three years, the number of enterprises having an API program is expected to increase by 150 percent.
[Read the full article at FinExtra.com]

New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services

By News

SAN FRANCISCO, CA–(Marketwired – Nov 5, 2015) – The Linux Foundation, the nonprofit organization dedicated to accelerating the growth of Linux and collaborative development, today is announcing the Open API Initiative. Founding members of the Open API Initiative include 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, Restlet and SmartBear.

The Initiative will extend the Swagger specification and format to create an open technical community within which members can easily contribute to building a vendor neutral, portable and open specification for providing metadata for RESTful APIs. This open specification will allow both humans and computers to discover and understand the capabilities of the respective services with a minimal amount of implementation logic. The Initiative will also promote and facilitate the adoption and use of an open API standard.

“Swagger is considered one of the most popular frameworks for building APIs. When an open source project reaches this level of maturity, it just can’t be managed by one company, organization or developer,” said Jim Zemlin, executive director at The Linux Foundation. “The Open API Initiative will extend this technology to advance connected application development through open standards.”

[Read the full article on Reuters]