search

elastic / elasticsearch

Free and Open Source, Distributed, RESTful Search Engine
https://www.elastic.co/products/elasticsearch
Other
1.23k stars 24.85k forks source link

Document the relationship between Accept, Content-Type headers and a format parameter #62294

Open pgomulka opened 4 years ago

pgomulka commented 4 years ago

it is not clearly documented what happens when format parameter has a different value then Accept header. Should we allow this? should format parameter override the value from Accept header? Or maybe we should validate and throw exception? example https://www.elastic.co/guide/en/elasticsearch/reference/current/cat.html#_response_as_text_json_smile_yaml_or_cbor

Also should Content-Type be allowed to be used in the same way as Accept header when body is not present? this is for instance not documented in https://www.elastic.co/guide/en/elasticsearch/reference/master/sql-rest-format.html but allowed

elasticmachine commented 4 years ago

Pinging @elastic/es-docs (>docs)

elasticmachine commented 4 years ago

Pinging @elastic/es-core-infra (:Core/Infra/REST API)

pgomulka commented 4 years ago

cc @elastic/es-ql as it affects its response formats

pgomulka commented 3 years ago

We discussed this on core-infra sync on 14th Jan. We concluded that the current logic should stay and the action is to document this.

We should still allow format to override the Accept header - this is a common way users call our api and the only way to change a response content-type in cabana

At the same time we still allow Accept header to be used (assuming format is not present). The Accept header should can have a content negotiation syntax (just one media type) but it will be ignored. This syntax is set on Accept header by browsers when calling API when requesting an URL.

Content-Type - we always expect it to be present when a body is on a request. It will have the next precedence over format and Accept. It is not strictly following the RFC (which does not expect request Content-Type to be used as response Content-Type). This we think will still be convenient for users.

When these 3 steps do not indicate a response content type, the default media-type remains JSON