Open michaelkourlas opened 8 years ago
Is compression
the right name for this? Shouldn't this be more generally something like transfer-encoding
?
@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.
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.
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?
@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.
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.
Content-Encoding
is not just compression, and specifies a list of supported content-coding
s.
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
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
andAccept-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 asAccept
,Content-Type
andAuthorization
, are already represented by dedicatedconsumes
/produces
andsecurity
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"
:"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 aContent-Encoding
header with a value consisting of any one of the items in the array."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 aContent-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
ofgzip
,deflate
, orcompress
, and is capable of sending responses with aContent-Encoding
ofgzip
ordeflate
: