Proposal: Support for HTTP compression

[michaelkourlas]

This is a proposal to add support for HTTP compression to version 3.0 of the OpenAPI specification.

Rationale for this change

At present, there is no robust way to determine from an OpenAPI specification what HTTP encodings a server is willing to accept for requests or is willing to encode responses in.

It is possible to list the Content-Encoding and Accept-Encoding HTTP headers as optional parameters in request and response objects, but this approach is complex and difficult to understand. Moreover, other standard HTTP headers, such as Accept, Content-Type and Authorization, are already represented by dedicated consumes/produces and security attributes.

Proposed addition to the specification

One way to implement support for HTTP compression would be to add a field to the OpenAPI Object called "compression" that maps to a Compression Object.

The Compression Object would have two fields, "consumes" and "produces":

• The "consumes" field would map to an array of strings; each string is an encoding that the API is willing to accept in HTTP requests. In other words, the server is prepared to accept requests with a Content-Encoding header with a value consisting of any one of the items in the array.
• The "produces" field would map to an array of strings; each string is an encoding that the API is prepared to send in HTTP responses. In other words, the server is prepared to send responses with a Content-Encoding header with a value consisting of any one of the items in the array.

It may be a good idea to allow the global compression settings to be overridden on a per-path basis by adding a "compression" field to the Path Item Object as well.

Example

The following snippet describes an API that can accept requests with a Content-Encoding of gzip, deflate, or compress, and is capable of sending responses with a Content-Encoding of gzip or deflate:

"compression": {
    "consumes": [
        "gzip",
        "deflate",
        "compress"
    ],
    "produces": [
        "gzip",
        "deflate"
    ]
}

[ePaul]

Is compression the right name for this? Shouldn't this be more generally something like transfer-encoding?

[michaelkourlas]

@ePaul: If you want to name the field after an HTTP header, then I think the most appropriate name is content-encoding. The name transfer-encoding would imply that the field has something to do with the Transfer-Encoding HTTP header, which isn't true.

[ePaul]

You are right, I mixed this up. Content-Encoding is the right thing here. My point would be that not just compressions are possible encodings, also other stuff like encryption.

[darrelmiller]

I don't understand why inventing a new OpenAPI property that does the same thing as defining the Accept-Encoding header is useful. What do you see as "complex and difficult" about using the Accept-Encoding header?

[michaelkourlas]

@darrelmiller: Well, as I mentioned above, the OpenAPI spec already has properties to represent important HTTP headers like Accept, Content-Type and Authorization. This arguably wasn't necessary, either. For example, instead of using the consumes property, you could simply include a required Content-Type header parameter for each path in your API spec.

I wasn't involved in the development of the OpenAPI spec, but I presume these headers were given their own properties because the header parameter type is supposed to be for "custom headers". These headers aren't custom headers; they are standard headers critical to the function of all HTTP APIs and should be explicitly highlighted rather than buried in the parameter list for each request. I think the same logic applies to the Accept-Encoding and Content-Encoding headers.

[haam]

I think this is important for generated clients to include code to handle compression. For example, we can include an Accept-Encoding header as a "custom" header, but the generated client won't know to automatically decompress a compressed response.

[ioggstream]

Content-Encoding is not just compression, and specifies a list of supported content-codings.
It is not an easy header field to manage, because the follow response contents are all different
and the server might negotiate them.

similar reasoning are valid for Content-Language.

content-type: application/json
content-encoding: gzip, br

content-type: application/json
content-encoding: gzip

content-type: application/json
content-encoding: br

content-type: application/json
content-encoding: br, gzip