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.
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:
- OpenAPI contribution guidelines
- Submit an OAS Issue
- Apply to become an OAI Member
- Join a TSC call
- Or reach out to Neal Cadin, Linux Foundation, or Darrel Miller, Microsoft
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:
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:
- AsyncAPI contribution guidelines
- Submit an Issue
- Sponsor AsyncAPI
- Join AsyncAPI Slack channel
- Join a meeting
- Email : [email protected]
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:
- View the Building Blocks for HTTP APIs (httpapi) charter
- Subscribe to mailing list
- Create IETF Account
- Contacts: Mark Nottingham, Erik Wilde, Barry Leiba, Darrel Miller, Rich Salz
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:
- Join the WoT Interest Group
- Attend a weekly WoT meeting
- View the Web of Things Interest Group Charter to learn more.
- Join W3C
- Organizer Email: [email protected]
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:
- gRPC Contribution Guidelines
- Draft a change proposal
- Attend a gRPC Community Meeting
- Chat with contributors on Gitter
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.
- JSON Schema Contribution guidelines
- JSON Schema on StackOverflow
- Join the json-schema Slack channel
- Support JSON Schema on Open Collective
- Follow @JSONSchema on Twitter
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.
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.
Source: Nordic APIs