02-18-2022 API Specifications Weekly

[doc-jones]

This is the weekly report across five of the leading API specifications, providing a snapshot of these communities that can be used to develop awareness, quantify the scope of, and increase engagement within these communities.

People

Identify one person each week who is doing interesting things within each of these formats.

• OpenAPI

  • Name: Karen Etheridge
  • Description: Staff Software Engineer, fastly
  • Twitter:
  • Linkedin: https://www.linkedin.com/in/karenetheridge/
  • Github: https://github.com/karenetheridge

• AsyncAPI

  • Name: David Boyne
  • Description: Tech Lead, Open technologies at Postman, AsyncAPI Initiative
  • Twitter: https://twitter.com/boyney123
  • LinkedIn: https://www.linkedin.com/in/david-boyne/
  • Github: https://github.com/boyney123

• JSON Schema

  • Name: Austin_Wright
  • Description: Editor, JSON Schema
  • Twitter: https://twitter.com/awwscript
  • LinkedIn: https://www.linkedin.com/in/austin-wright-74958959/
  • Github: https://github.com/awwright

• GraphQL

  • Name: Rob Richard
  • Description: Senior Director, Front-End Engineering
  • Twitter: https://twitter.com/rob_richard
  • LinkedIn:
  • Github: https://github.com/robrichard

• gRPC

  • Name: Google team members emails and names masked in googlegroup
  • Description:
  • Twitter:
  • LinkedIn:
  • Github:

Adoption

Identify one company or organization that has adopted one of each of these formats (head start available here: OpenAPI, AsyncAPI, JSON Schema)

• OpenAPI

  • Name: Develop ASPdotNET Core apps using OpenAPI tools
  • Description of Use: Microsoft.dotnet-openapi is a .NET Core Global Tool for managing OpenAPI references within a project.
  • URL: https://docs.microsoft.com/en-us/aspnet/core/web-api/microsoft.dotnet-openapi?view=aspnetcore-6.0

• AsyncAPI

  • Name: IBM API Connect
  • Description of Use:
  • URL: https://www.ibm.com/cloud/api-connect

• JSON Schema

  • Name: Event Catalog
  • Description of Use: A plugin for AWS Event Bridge
  • URL: https://twitter.com/boyney123/status/1484529334627049473

• GraphQL

  • Name: Salsify
  • Description of Use: Automated schema generation and breaking change detection make building and evolving backend GraphQL services a breeze while automated type generation and response mocking help us consume those APIs on the frontend.
  • URL: https://www.salsify.com/blog/engineering/supercharging-development-at-salsify-with-graphql

• gRPC

  • Name: Lyft
  • Description of Use: Lyft uses gRPC to transmit the location of a vehicle in a continuous stream of gRPC messages.
  • URL: https://www.redhat.com/architect/grpc-use-cases

The Beat

Make sure we are covering the beat each week and surfacing relevant information from across the communities.

Any interesting issues? (OpenAPI, AsyncAPI, JSON Schema. GraphQL, gRPC)

• OpenAPI

  • Title: Define the need for documentation beyond the current scope of the OAS
  • Description: The OAS currently focuses on discrete API operations with no implications of what happens before or after this instance of an API call. There are scenarios where there are specific or implied relationships between a group of APIs that can not be expressed in a machine readable format in the OAS and hence can only be communicated out of band by some other means. The draft proposal is to create a machine readable format that would be useful to tool providers, now or in the future, that provides actionable instructions of the intended relationships within a group of APIs.
  • URL: Define the need for documentation beyond the current scope of the OAS OAI/OpenAPI-Specification#2872

• AsyncAPI

  • Title: Make Server Variables Object available as reusable objects under the Component object.
  • Description:
  • URL: Make Server Variables Object available as reusable objects under the Component object asyncapi/spec#707

• JSON Schema

  • Title: jsonschema: declarative language or media type?
  • Description: a JSON-based format for describing the structure of JSON data
  • URL: [2022-01-06] Review Default Value Coercion spec text to ensure alignment with reference implementation graphql/graphql-wg#879

• GraphQL

  • Title: Review Default Value Coercion spec text to ensure alignment with reference implementation
  • Description: Advancing Default Value Validation/Coercion
  • URL: [2022-01-06] Review Default Value Coercion spec text to ensure alignment with reference implementation graphql/graphql-wg#879

• gRPC

  • Title: AuthContext properties are not reset on subsequent calls
  • Description: It seems the behavior is expected. The auth_context is per-channel, and AuthMetadataProcessor::Process calls per-rpc. For a particular channel, we can have multiple rpc requests. When you update the information in one rpc, it's likely you will see the change in another rpc process request.
  • URL: AuthContext properties are not reset on subsequent calls grpc/grpc#28809

Any interesting discussions? (OpenAPI, AsyncAPI, JSON Schema, GraphQL, gRPC)

• OpenAPI

  • Title: What is the meaning of a Media Type Object with no schema defined?
  • Description: At the moment, we only support JSON Schema for the Schema Object, meaning you can only describe JSON payloads (and to some limited extent XMLs). Had we supported things like XSD (which we may in the future), that would allow you to define schemas (or something similar) for additional media types.
  • URL: What is the meaning of a Media Type Object with no schema defined? OAI/OpenAPI-Specification#2874

• AsyncAPI

  • Title: Proposal for community building/scaling goals for 2022
  • Description: There are 3 big topics for 2022 that should be priority 1, followed by many other suggestions.
  • URL: Proposal for community building/scaling goals for 2022 asyncapi/community#193

• JSON Schema

  • Title: Forward compatibility with must-understand keywords
  • Description: When submitting JSON Schema as an Internet media type (e.g. application/schema+json), one of the potential problems in JSON Schema is: how does it support forward compatibility?
  • URL: Forward compatibility with must-understand keywords json-schema-org/community#119

• GraphQL

  • Title: Enforcing delivery order of payloads - Defer-Stream WG
  • Description: It was discussed in the 2021-07-01 WG meeting and 2021-12-02 WG meeting and the group agreed that responses like this must be ordered to ensure payload paths do not reference fields that have not been sent yet.
  • URL: Enforcing delivery order of payloads graphql/defer-stream-wg#17

• gRPC

  • Title: Java 8 may drop support for gRPC in Q2 2022
  • Description: googlegroups discussion
  • URL: https://groups.google.com/g/grpc-io/c/bC7vpryx0ko

Any interesting news?

• OpenAPI

  • Title: Postman Now Supports OpenAPI 3.1
  • Description: We are excited to announce that the Postman API Platform now supports OpenAPI 3.1 files. OpenAPI 3.1 is the latest version of OpenAPI and was released in February of last year.
  • URL: https://blog.postman.com/postman-now-supports-openapi-3-1/

• AsyncAPI

  • Title: Version 3.0 is coming
  • Description:
  • URL:

• JSON Schema

  • Title: Changes Community Meeting to US and Canada friendly time zones
  • Description: Improvements to engagement
  • URL: https://twitter.com/jsonschema/status/1494260019222749184

• GraphQL

  • Title: Release of graphql-parser and graphql-encoder rewritten in Rust
  • Description: Nothing in these libraries is specific to Apollo, and can freely be used by other projects which need standards-compliant GraphQL tooling written in Rust.
  • URL: https://twitter.com/BnJ25/status/1492137294869975043

• gRPC

  • Title: Calendar invitation for the first gRPC Community Meetup of 2022
  • Description: In this talk, Ali Hassan, Entrepreneur and engineer in computer science & economics. Founder of WisdomEnigma Inc will present: “gRPC Connection”
  • URL: https://groups.google.com/g/grpc-io/c/6th2GjvuGWo

Any interesting tweets?

• OpenAPI

  • Title: Use Amazon EventBridge?
  • Description: I'm working on a new plugin for EventCatalog that will be released next week...JSONDraft4 and OpenAPI Schemas
  • URL: https://twitter.com/boyney123/status/1484529334627049473

• AsyncAPI

  • Title: AsyncAPI Spec 3.0 meeting
  • Description:
  • URL: https://twitter.com/AsyncAPISpec/status/1493978161171689475

• JSON Schema

  • Title: Open Community Working Meeting calls are changing time
  • Description: We had low attendance from the EU work time zone friendly call, so we are shifting to US/CA work time friendly.
  • URL: https://twitter.com/jsonschema/status/1494260019222749184

• GraphQL

  • Title: The new graphql-ws protocol added to GraphiQL
  • Description: Optional utility to generate a fetcher with support for @defer, @stream via the IncrementalDelivery protocol
  • URL: https://twitter.com/rikki_js/status/1353434588954193920

• gRPC

  • Title: N/A
  • Description:
  • URL:

Any interesting videos?

• OpenAPI

  • Title: How to add query paramters to API definition in OpenAPI specification 3.0 (OAS)
  • Description:
  • URL: https://www.youtube.com/watch?v=864mh7LlZSs

• AsyncAPI

  • Title: AsyncAPI Spec 3.0 first meeting
  • Description: Twitter Spaces - recorded audio only
  • URL: https://www.youtube.com/watch?v=sK5eAJtScAo

• JSON Schema

  • Title: What's the role of "JSON Schema in API Design and Development"?
  • Description: Listen to Ben Hutton @jsonschema specification lead, talking about why it matters and how it's used in APIs and description formats such as @OpenAPISpec and @AsyncAPISpec.
  • URL: https://twitter.com/dret/status/1494278196384219136

• GraphQL

  • Title: What is Apollo Federation
  • Description: Apollo Federation is a more intuitive option for building distributed GraphQL architectures. It combines multiple GraphQL Schemas into a single data graph.
  • URL: https://www.youtube.com/watch?v=v_1bn2sHdk4&t=81s

• gRPC

  • Title: Building Java microservices with gRPC
  • Description: Ketkee Aryamane covers the fundamentals of gRPC and its key features. Ketkee starts with the basic theory behind RPC and the HTTP/2 protocol, then shows how to build two gRPC services in Java from scratch using protocol buffers, and connects those services with each other using gRPC. She also covers how to generate clients that can invoke those services. If you’re a developer looking for new ways of developing web services, following along with Ketkee as she builds microservices from scratch is a great way to learn new concepts, while also seeing these concepts put to practical use.
  • URL: https://www.linkedin.com/learning/building-java-microservices-with-grpc/microservices-with-grpc

Any interesting tools?

• OpenAPI

  • Title: Steampipe
  • Description: This example shows how to query the OpenAPI example definitions.
  • URL: https://github.com/turbot/steampipe-samples/blob/main/config-yaml/README.md

• AsyncAPI

  • Title:
  • Description:
  • URL:

• JSON Schema

  • Title:
  • Description:
  • URL:

• GraphQL

  • Title: Pothos
  • Description: Pothos is a plugin based GraphQL schema builder for typescript.
  • URL: https://pothos-graphql.dev

• gRPC

  • Title: Wireshark
  • Description: Can be used to debug gRPC traffic
  • URL: https://grpc.io/blog/wireshark/

Any interesting events?

• OpenAPI

  • Title: N/A
  • Description:
  • URL:

• AsyncAPI

  • Title: N/A
  • Description:
  • URL:

• JSON Schema

  • Title: N/A
  • Description:
  • URL:

• GraphQL

  • Title: GraphQL Summit 2021
  • Description: Apollo GraphQL conference
  • URL: https://summit.graphql.com

• gRPC

  • Title: Open Source Summit 2022
  • Description: CFP includes API topics likely this will include multiple of OT Specs.
  • URL: https://events.linuxfoundation.org/open-source-summit-north-america/

Scope

Quantifying the scope of the communities week by week.

• ↑ increase from last week
• ↓ decrease from last week
• nc no change from last week

Twitter Followers

Measuring the activity that occurs across Twitter

• OpenAPI: 7,730 ↑
• AsyncAPI: 3,043 nc
• JSON Schema: 884 ↑
• GraphQL: 72,050 ↑
• gRPC: 15,924 ↑

Github Scope

Measuring the activity occurring across Github

• OpenAPI

  • Github Repo Watch: 864
  • Github Repo Forks: 8,091
  • Github Repo Stars: 23,132

• AsyncAPI

  • Github Repo Watch: 49
  • Github Repo Forks: 172
  • Github Repo Stars: 1,958

• JSON Schema

  • Github Repo Watch: 102
  • Github Repo Forks: 234
  • Github Repo Stars: 2,500

• GraphQL *

  • Github Repo Watch: 544
  • Github Repo Forks: 1,111
  • Github Repo Stars: 13,626

• gRPC

  • Github Repo Watch: 1,357
  • Github Repo Forks: 8,784
  • Github Repo Stars: 33,387

Stack Overflow Questions

Measuring the activity on Stack Overflow using number of overall questions.

• OpenAPI : 9,622 ↑
• AsyncAPI: 126 nc
• JSON Schema: 32,615 ↑
• GraphQL: 44,692 ↑
• gRPC: 16,352 ↑