Add support for newer HTTP versions (2/3)

[christosgkoros]

Context
REST APIs should evolve to utilize the capabilities of the newer versions of the HTTP protocol.

Problem
OAS does not support different protocol information and the new version's ability for bidirectional communication. Since the specification and documentation of an API are essential for collaboration, this is a limiting factor in exploration and innovation with newer HTTP versions.

Solution

1. Optionally define on API and path level the communication protocol (HTTP 1.1 / HTTP2 / HTTP3)
2. Ability to define streams of requests and responses
3. Ability to define different possible schemas for a request and response

The Specification format should not limit the capabilities of the APIs by leveraging newer underlying protocol versions.

[handrews]

Is it necessary to explicitly state the HTTP version, or would it be better to just ensure that OAS can describe the functionality that newer versions offer?

[christosgkoros]

Hey @handrews

On the one hand, adding lower-level information, like the protocol version, does not add much to the OAS.

On the other hand, the functionalities added from those newer versions can significantly alter the way of working.
From a consumer perspective, the human can easier understand the request/response patterns and the tool can decide its approach (f.e. a gateway to expose a different type of proxy based on the version(

Wouldn't it be better to have an Optional indicator that an API is HTTP2+?

[handrews]

@Gorosc I guess I'm having a bit of trouble understanding how one would use an explicit HTTP2+ marker vs how one would use specification information that implies HTTP2+ and/or how one would simply use the runtime reality of being able to negotiate HTTP2 or HTTP3 for a session.

[christosgkoros]

Hey @handrews

I am glad we agree that HTTP2+ features should be described in the OAS. I don't know if this is being worked on elsewhere. Otherwise, we could come up with a proposal.

Regarding the protocol version, it mostly has to do with the cognitive part and simplifying resolving it w/o having to introspect the operations.

[darrelmiller]

I could imagine advertising H2 or H3 support in the server object.

Could you suggest how you might model H2 streaming differently than for example using chunked encoding in HTTP/1.1? Currently my assumption is if a response payload is application/json-seq then that result may be streamed. How would you suggest changing OAS to help describe the API?

Mostly streaming and multiplexing of requests and responses are transparent to the application model, so I'm not sure how they might surface in an API description.

[rafalkrupinski]

I thought HTTP 2&3 weren't supposed to make any semantic changes to the protocol.

I'd like to have the version in the description just so the code can speed-up connection by not trying HTTP version higher than max.

[handrews]

Thanks for specifying a use case! Do you see scenarios where that speed-up would be significant in some way? This level of performance tuning is not my area of expertise, I just think it might help to document the conditions under which this is beneficial. Or perhaps a better way to phrase it is: Is figuring out the HTTP version to speed up connection something people typically do to optimize API performance? Is it ever a major percentage of API interaction time?

[rafalkrupinski]

Do you see scenarios where that speed-up would be significant in some way?

Trying to use H3 with servers that don't support it, particularly when using command line tools, which can't re-use connections, and you don't want to wait for the result.

This level of performance tuning is not my area of expertise

Mine neither, but just as an example, a few years back someone complained that python library httpx was unnecessarily loading TLS stack for plain http connections. Who cares about non-tls connections in 2020s? Well, sometimes you have two microservices running on one machine.

I just think it might help to document the conditions under which this is beneficial

The issue with H3 is that the client sends a UDP packet and waits for either a response or timeout, after which it can fallback to TCP and negotiate 1.1 vs 2 with ALPN. If It knows the server doesn't support H3, It can skip waiting for the timeout. Most of the times this could be cached, so that only the first interaction is affected, but not all environments allow persisting data.

Also you may need to decide between two http client libraries, one older, stable but only supporting HTTP/1.1 and another, newer, supporting H2/3 but with unstable API (e.g. python's requests vs httpx).

When writing a generator, the generated code could avoid depending on libraries specific to particular HTTP version in order to limit potential dependency hell for its users. [edited: applies both to generated and human-written libraries]

Is figuring out the HTTP version to speed up connection something people typically do to optimize API performance? Is it ever a major percentage of API interaction time?

Can't speak for others. It's not currently a problem in Python, since H2&3 are poorly supported.

[handrews]

@rafalkrupinski thank you for the detailed replies! This will definitely help in assessing whether / how to add this to the OAS. Since @darrelmiller already seems open to at least advertising support levels, that much seems likely to be accepted. I'll add it to next week's meeting agenda to see if we can get a decision on moving to an ADR (see PR #89 for an explanation of our de-facto current process).