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

Start by reviewing the OpenAPI 3.0 OpenAPI Object and Path Item Object definitions, then compare the proposed Compression Object fields with the existing consumes and produces attributes. Done means the compression model, scope, and override behavior are agreed and incorporated into the specification.