You may be familiar with API specifications like OpenAPI or AsyncAPI, but who are the groups maintaining these standards? And, how can you get involved in these communities to help shape the API revolution?

Here are the top standard bodies molding the API industry as we know it. These initiatives, working groups, and collaborative projects are actively standardizing the specifications, formats, and schemas that bring interoperability to the API world.

For technology companies, having a presence in standards groups is a must. For API-related organizations, it’s no different. Contributing to these projects could help solo developers or companies actively establish their sector’s integration standards. Thankfully, these open-source initiatives welcome contributors.

Of course, contribution policies vary from each to each. So, I’ve reviewed each group and attempted to make sense of their processes. I’ve included ways to get involved, such as contribution guidelines, links to make public pull requests, and membership information.

This article was inspired by the vibrant community discussion and emerging standards bodies present at the API Specifications Conference 2020. Thank you to The Linux Foundation for hosting!

1. OpenAPI Initiative

OpenAPI Initiative (OAI), supported by the Linux Foundation, is an open-source community building a vendor-neutral metadata for RESTful APIs. Formerly known as Swagger, OpenAPI Specification (OAS) has emerged as the defacto format for describing web APIs. OAS is described here on Github.

The OpenAPI Technical Steering Committee (TSC) steers OpenAPI Specification (OAS) development. The TSC considers community feedback, open issues, and pull requests when updating the spec. Lorna Mitchell of Vonage, and early OpenAPI contributor, describes OpenAPI as an “open process” where “patchers are generally welcome.”

Ultimately, the OAI has a bureaucratic echelon of OAS governance — with a Governing Board, a Technical Oversight Board, and a Technical Steering Committee, and multiple working groups. Don’t expect an easy process when making requests for significant changes. The Project Charter describes the OpenAPI Initiative process and membership practices. Here are some ways to get involved:

2. GraphQL Foundation

GraphQL, the data query language and specification, was initially developed at Facebook. Now, it’s publicly open-sourced, hosted under the Linux Foundation, and the community largely dictates its future.

The GraphQL operates the GraphQL Working Group, a monthly meeting of maintainers of GraphQL tools and libraries, open to members. You must apply to become a member — membership application here. The GraphQL Foundation offers a corporate specification membership, good for companies, and an individual membership for individual developers or students.

GraphQL itself is open for public pull requests, and spec editors often merge fixes, improvements, or small errors. However, larger changes are dictated by the working group. Here are some ways to get involved:

3. AsyncAPI Initiative

Did you know the first AsyncAPI Initiative supporters were announced at Nordic APIs Platform Summit in 2018? Nordic APIs has shared AsyncAPI founder Fran Méndez’s thoughts on asynchronous messaging in blog posts and talks for years now, and I’ve been a proponent of AsyncAPI since its debut.

AsyncAPI is like OpenAPI, but for asynchronous protocols such as MQTT. The AsyncAPI Specification is designed to describe event-driven, messaging, and IoT situations where communication is not synchronous. Since its debut as a new API definition standard, AsyncAPI has largely been shaped by community input. Fran Méndez and Łukasz Górnicki actively maintain AsyncAPI. The project welcomes contributors on Github.

AsyncAPI offers a playground to generate documentation and validate AsyncAPI specifications, and the surrounding community has created many tools, from doc generators, validators, mock environments, and more. Here are some ways to get involved:

4. Building Blocks for HTTP APIs — IETF Working Group

IETF is well known as the standard body maintaining and developing the core specifications for HTTP. IETF members have now outlined a new charter for the Building Blocks for HTTP APIs Working Group.

HTTP is not only standard for the web but ubiquitous for machine-machine communication. Since most web APIs use HTTP as a standard communication protocol, “HTTP APIs” has become an umbrella term to describe such services.

The proposed Building Blocks for HTTP APIs Working Group (httpapi) thus intends to develop new HTTP headers and abilities to support nuanced HTTP API needs. For example, a universal pagination standard could be set for HTTP APIs. Signing for HTTP messages, or a Rate Limit Header Field are potential drafts that could bolster HTTP API standards.

“Good protocols are defined by broad community in the open,” said Mark Nottingham of IETF in a resent ASC talk. According to the charter, new working items will be added after a Call of Adoption on the working group mailing list and WG director’s approval. The group is still rather new, but here are some ways to get involved:

5. W3C Web of Things Interest Group

Technology companies working with Internet of Things (IoT) devices may find the Web of Things Interest Group especially interesting. This W3C interest group provides a public forum for accelerating web standards for IoT devices.

The W3C Web of Things (WoT) Working Group is standardizing a Thing Description (TD), an API description format for IoT devices. With standard IoT descriptions, developers could string together cool IoT mashups and device-to-device flows.

At a “Thing Level,” Web of Things (WoT) Thing Description includes semantic annotations, thing metadata, security, interaction definitions, and links to other documents. The working group also supports a playground for validation, Binding Templates, a Scripting API for protocol-agnostic communication, and other tooling.

WoT seems to be governed by companies with feet in hardware and software, like Intel and Siemens. To get involved, they hold a weekly Wednesday call for the group and guests. Each Task Force has its own weekly calls, where the public is open to ask questions. Here are some ways to get involved:

6. gRPC

While less of a standard and more of an open-source project, gRPC has nonetheless seen rapid adoption in the API space. gRPC formalizes a process for server to client communication, using client stubs that interact with server resources. gRPC was born out of Google’s single general-purpose RPC infrastructure called Stubby. In 2015, it open-sourced an update of the tool to much fanfare — gRPC now powers many microservices and the “last mile” of computing (mobile, web, and IoT). Here are some ways to get involved:

7. JSON Schema

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents, says json-schema.org. A language and platform agnostic tool, JSON describes a set of constraints for interaction between JSON documents. Since JSON is a common REST API data format, JSON Schema has been growing in use and importance.

Honorable Mentions

In this post, I largely focused on standards bodies around API specifications, but there are certainly other description formats and protocols related to APIs with their own groups. Others include:

  • OData: An open protocol standardized by OASIS. Allows the creation and consumption of queryable and interoperable RESTful APIs in a standard way.
  • ALPS by Mike Amundsen.
  • Identity standards involved in API security: OAuth 2.0, OpenID Connect, SCIM.
  • FHIR Core Work Group: Fast Healthcare Interoperability Resources (FHIR) is an HL7-defined standard for healthcare records.
  • Hydra is a framework for developing hypermedia-driven web APIs.
Did I leave out an important API industry initiative? Please comment below and I’ll consider adding it to the list above.

Standard Bodies Need Diversity

It may seem like specification wars all over again, but in actuality, many of these open standards groups complement each other or support unique industries where specific styles are concerned.

Participating in open-source communities helps move their projects forward. Whether it’s fixing an error, or requesting a new feature, actively volunteering to improve these standards can invigorate the overall economy. It’s also crucial for ancillary tools that consume these specifications to stay on top of their evolution.

Standard bodies in the API Industry usually are quite open to bringing in new perspectives to help guide the momentum. It’s this diversity that can ensure specifications meet the majority of use cases and consider fringe scenarios as well. For example, OpenAPI Initiative is encouraging unique verticals to share their perspective. There is now a travel-themed OpenAPI Working Group to help OpenAPI evolve with the travel industry.

Keep in mind; it’s not always an easy process! The reality is standard bodies can be quite slow-moving. “Every added functionality makes a specification more complicated,” reminded Darrell Miller at ASC. The reason complex standardizing processes exist is they must encompass changes that work well within an entire industry. A potential downside of standards is the lowest common denominator effect.

Final Thought: Contribute

Creating standardized methods for describing APIs is vital for promoting industry interoperability. Open contribution policies help specifications support current or old stacks while future-proofing them to evolve in new directions.

Standard formats can also enable cool tools for documentation generation, sandboxing APIs, and discovery, while allowing easier partner integrations. Not to mention, having a spec as a source of truth can guide design-first approaches and streamline company-wide style.

All the projects above have varying policies. Some are more open-source in nature; some are sector-specific or may not be as inclusive; some accept financial contributions for a spot on the governing board, etc. In general, though, all welcome new contributions and ideas.

Whether you are a contributor, maintainer, or implementation developer, being part of the ecosystem is important. At the very least, viewing open Github issues or discussions can help you have a say on emerging standards. Because, without a voice in the creation of API standards, you may not have a voice in the API economy at all.

Bill Doerrfeld

Bill Doerrfeld is a tech journalist and API specialist, focusing on API economy research and marketing strategy for developer programs. He is the Editor in Chief for Nordic APIs. He leads content direction and oversees the publishing schedule for the Nordic APIs blog. Bill personally reviews all submissions for the blog and is always on the hunt for API stories; you can pitch your article ideas on our Create With Us page. Follow him on Twitter, or visit his personal website.