Exception template for response body for HTTP status code 406

[heidivanparys]

Inspired by #73 :

According to RFC 7231:

The 406 (Not Acceptable) status code indicates that the target resource does not have a current representation that would be acceptable to the user agent, according to the proactive negotiation header fields received in the request (Section 5.3), and the server is unwilling to supply a default representation.

The server SHOULD generate a payload containing a list of available representation characteristics and corresponding resource identifiers from which the user or user agent can choose the one most appropriate. A user agent MAY automatically select the most appropriate choice from that list. However, this specification does not define any standard for such automatic selection, as described in Section 6.4.1.

[...]

A specific format for automatic selection is not defined by this specification because HTTP tries to remain orthogonal to the definition of its payloads. In practice, the representation is provided in some easily parsed format believed to be acceptable to the user agent, as determined by shared design or content negotiation, or in some commonly accepted hypertext format.

So could an error response format be defined to be used in the case of a 406, following RFC 7807? Having the following additional members:

• acceptable_charsets
• acceptable_content_encodings
• acceptable_languages
• acceptable_media_types

E.g.:

# Request
GET {root}/ HTTP/1.1
Accept: application/json
Accept-Language: *;q=0.0

# Response
406 Not Acceptable
Content-Type: application/problem+json
Content-Language: en

{
    "type": "http://www.opengis.net/to/be/decided",
    "title": "Not Acceptable",
    "status": 406,
    "detail": "This server supports the following languages: English, Danish.",
    "instance": "/collections",
    "acceptable_languages": [ "en", "da" ]
   }

The actual use case behind this specific example is INSPIRE: according to the INSPIRE legislation, it must be possible to retrieve a list of supported languages from a download service. As long as the response body supplied in a machine-readable format sent with HTTP status code 406, is not standardised, it is not possible (at least not without INSPIRE itself defining some standard, and that is to be avoided) to build applications that programmatically can access a list of supported languages and display that information to an end user.

[cportele]

I think we have to be careful here.

1. If there is a requirement that a server has to support multiple languages or evaluate the Accept-Language parameter, this goes beyond OGC API Common (at least a part 1).

2. While it is entirely consistent with HTTP to return 406, if there is no language match, this is not the typical behaviour. For example, my browser will send something like de,en;q=0.5, but if there is no German or English representation, I always get whatever language is available, which is what I and most others prefer. This is also consistent with HTTP since one of the pre-conditions for 406 is that "the server is unwilling to supply a default representation". Most web servers will happily serve content in French, Danish or Japanese to me.

3. Servers that support languages could respond as described in 2. above and at the same time include rel=alternate links with hreflang attributes to the same resource in other languages as described in http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#string_i18n. Then a client could determine the available languages, if it does not like the returned language. However, requiring such behaviour requires new OGC API standards to comply to (that noone has yet started to work on).

I think INSPIRE should be open to a pragmatic interpretation of the legal text that only requires language support in a server where the data provider really wants to support multiple languages for a dataset in a single API. Otherwise the number of tools that can be used (now) for INSPIRE will likely be small.

As an aside, in DCAT each language would be a separate Distribution, so maybe the metadata could be used to publish the dataset languages. There could be a link to the DCAT metadata from the API, which is also not required by the standard, but easier to support than full language support. This way the list of languages would be "retrievable from the download service".

[heidivanparys]

Ok, the INSPIRE use case was just the background, I suggest we discuss that in the issue referenced above instead.

Let's change the example to a failure of media type negotation, instead of a failure of language negotiation.

From section 7.7 in the book ALLAMARAJU, Subbu. RESTful Web services cookbook. O’Reilly Media, 2010. ISBN 978-0-596-80168-7. :

The general advice is:

When the server cannot serve a representation that meets the client’s preferences and if the client explicitly included a */*;q=0.0, return status code 406 (Not Acceptable) with the body of the representation containing the list of representations.

The example discussed is:

# Request
GET /user/001/followers HTTP/1.1
Accept: application/json,*/*;q=0.0

# Response
406 Not Acceptable
Content-Type: application/json
Link: <http://www.example.org/errors/mediatypes.html>;rel="help"
{
"message" : "This server does not support JSON. See help for alternatives."
}

In the discussion of this example the author states (highlighting is mine):

In this example, the server recognizes JSON but is unable to serve a representation of the resource in that format. Since the client request includes a q=0.0 for every other media type except application/json, a failure is acceptable for the client. Note that the server uses a JSON-formatted representation for the error message. It is quite reasonable for the server to implement error messages in commonly used formats. If not, return the error message in human-readable HTML format.

So my question in this issue is: would it make sense to standardize the error message returned with HTTP status code 406 for OGC APIs, using RFC 7807 as a starting point?

[cmheazel]

@cmheazel to validate that this issue has been addressed.

[cmheazel]

The recommended changes have been made.