Need to clarify section 2.3 about Accept Headers

[donbourne]

As reported by Tomas Langer (@tomas-langer) via the forum, we need to clarify the content in section 2.3 related to Accept header matching.

 according to spec it seems that if request matches JSON, I should reply with JSON.
So for example this Accept header:
text/plain;version=0.0.4;q=1,*/*;q=0.1
should return JSON format, as */* is supported.

There are no TCK tests related to this (e.g. a combination of accepted types) and the text in spec is not absolutely clear (e.g. what does "matches" mean? is it an exact match? or did I understand it correctly?)

Spec definition:
Data is exposed via REST over HTTP under the /metrics base path in two different data formats for GET requests:

• JSON format - used when the HTTP Accept header matches application/json.
• Prometheus text format - default response format when the HTTP Accept header does not match

any more specific media type like application/json. 





If we should honor the Accept header as it is designed, I should return Prometheus format any time text/plain has higher q than application/json (and vice versa).



Could somebody from the Metrics spec provide a clear answer to:

Should I honor the order and "q" in Accept header and return JSON only if application/json is preferred over text/plain, or should I return JSON if application/json is supported by the Accept header (supported means that at least one segment of Accept header matches application/json)?

[barchetta]

The spec should also explicitly state what the behavior should be if the Accept header is absent or */*

[pilhuhn]

What about

• JSON format - used when the HTTP Accept header matches application/json as best option.
• Prometheus text format - default response format when the HTTP Accept header does not match another format as better option. It is also the default for `*/*` or when no Accept header is given.
* If a client only explicitly requests media-types A and B (e.g. image/png and image/jpeg), but the server does not support it, a 406 "Not acceptable" return code (see https://httpstatuses.com/406 )
*  Note: implementations may support other formats and need to do the match accordingly.

[donbourne]

maybe...

text/plain - prometheus
application/json - json

implementations may support other formats (eg. text/xml)
prometheus takes precedence when ACCEPT header would equally accept both text/plain and application/json and there is no other higher precedence format
a 406 response code must be returned when ACCEPT header would not accept any of the supported formats
if no ACCEPT header is provided, return in prometheus format

[pilhuhn]

Implemented by #298