Proposal: Support for HTTP compression

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"
    ]
}

[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?

[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