Support for WebTransport over HTTP/3 QUIC

[shivarammysore]

I am building a new protocol H3Net (https://h3net.switchnomix.com) and we are using HTTP/3 QUIC. As we have to do bidirectional messaging, we have options of streaming, websockets and WebTransport. We believe WebTransport suits best for our use cases. Does OpenAPI schema have plans to support WebTransport endpoints which are not natively supported in OpenAPI 3.0? The specification and schema is available on the website and I am happy to provide more details as required. Thanks

[handrews]

@shivarammysore It's not clear to me what the OpenAPI Specification needs to do here. WebTransport seems to be operating at a different level than what the OAS does. Would this fit better with AsyncAPI?

[shivarammysore]

OAS currently supports HTTP/3 and WebSockets via AsyncAPI

Feature	WebTransport 🛜	WebSockets 🌐	OAS (OpenAPI Specification) 📜	AsyncAPI 📡
Purpose	Enables low-latency, bi-directional communication over HTTP/3.	Bi-directional, real-time messaging over a persistent connection.	Describes RESTful APIs, primarily synchronous request-response communication.	Describes event-driven, asynchronous APIs (e.g., WebSockets, Kafka, MQTT).
Protocol	HTTP/3 (QUIC-based)	Uses HTTP/1.1 or HTTP/2 for handshake, then upgrades to WebSockets.	HTTP/1.1, HTTP/2, HTTP/3	WebSockets, AMQP, MQTT, Kafka, NATS, etc.
Communication	Bi-directional, full-duplex streams with reliable/unreliable transport.	Bi-directional, full-duplex over a single TCP connection.	Client-server, synchronous (request-response).	Pub/Sub, event-driven, asynchronous messaging.
Transport	Runs over QUIC (UDP-based).	Runs over TCP.	Uses traditional HTTP request-response.	Uses messaging protocols (AMQP, MQTT, Kafka, WebSockets, etc.).
Reliability	Can be both reliable and unreliable (datagram support).	Reliable, but single TCP connection may cause head-of-line blocking.	Reliable, as it follows HTTP request-response semantics.	Reliable, depending on the transport (e.g., Kafka is durable, WebSockets are not).
Schema Standard	No schema standard, but works with JSON, Protobuf, etc.	No built-in schema definition; can use JSON, Protocol Buffers, etc.	OpenAPI 3.0/3.1 (YAML/JSON-based).	AsyncAPI 2.x (YAML/JSON-based).
Best For	Interactive apps, gaming, low-latency streaming, IoT, WebRTC-like scenarios.	Chat apps, notifications, interactive UI updates, low-latency communication.	REST APIs, API documentation, generating client/server code.	Messaging-based architectures, microservices, real-time applications.
Tooling Support	Limited, mostly experimental (Node.js, Go, Rust).	Widely supported (Node.js, Go, Python, Java).	Mature ecosystem (Swagger, OpenAPI Generator, Postman).	Growing ecosystem (AsyncAPI Generator, Event-driven platforms).
Example Use Case	Real-time multiplayer gaming, collaborative apps, interactive streaming.	Live chat, stock price updates, real-time collaboration.	REST API for CRUD operations in a web app.	Microservices event bus, IoT messaging, event-driven workflows.

Note that H3Net remains HTTP-based and does not natively fit into the traditional publish-subscribe model of Async API. Protocol-agnostic AsyncAPI is optimized for event-based systems too.

Our requirement: H3Net (with HTTP/3 and potentially WebTransport) supports low-latency, reliable messaging and can facilitate bidirectional communication. Hence the ask.

Currently, we maintain a valid OpenAPI 3.0 JSON schema. We then run a script to convert the same into WebTransport - mostly the same paths, etc but enables code generation with with openapi-generator-cli so that we can run the server with http3 quic.

Question: Is there something we can add to the OpenAPI spec schema so that code generation tools use the same schema to generate the "WebTransport" version in this case? Or do you have any different suggestions that I should explore?

Thanks

[handrews]

OAS currently supports HTTP/3 and WebSockets via AsyncAPI

Despite the similarity of the names, AsyncAPI is not part of the OpenAPI Initiative. We are focused on HTTP APIs, and based on this table, WebTransport, like WebSockets, makes only incidental use of HTTP to initiate sessions. We have previously determined that WebSockets are out of scope for this reason (see #2947, #2880 (pointing to AsyncAPI), or to go very far back, #55). AFAICT, the arguments against WebSockets also apply to WebTransport.

It's also not clear to me why it would be better to put WebTransport support in the OAS rather than either AsyncAPI or some independent specification. We need to be conscious of the implementation burden on tool providers. Having a separate spec means that different tool providers could build HTTP vs WebTransport tools, rather than adding a large amount of work for existing OAS implementations to expand into WebTransport.

This is not to close the door entirely, and I'm not someone who will make a final call one way or the other. But I don't currently see why OAS is the best home for this work.

[shivarammysore]

Thanks for the response @handrews much appreciated. I don't have great counter arguments. I will keep working on this.