Re: [httpapi] Last Call: <draft-ietf-httpapi-rfc7807bis-04.txt> (Problem Details for HTTP APIs) to Proposed Standard

[Ben Bucksch <[e-mail]>]

Hi Mark, hi all,

Thank you for authoring this spec. It is addressing a real need: Error 
messages are a serious problem point in most HTTP based APIs. Every API 
author creates their own error spec, with slightly different semantics, 
because the HTTP status does not adequately cover it. It's good to have 
error reporting specified consistently and sanely.

Sorry for raising this at the "last call", but I noticed a few issues 
that could pose problems in real world usage, and would be difficult to 
fix in hindsight:

1. Uncertainty created by the relative URIs used as IDs for problem 
"type" field

You are specifying problem "type" IDs as URIs. That's a good idea, it 
allows for scoping and teams to assign their own error IDs. However, 
allowing relative URIs creates significant real world problems:
* Most of the time, parsing of the errors will be adhoc. The chances 
that the client does not resolve the relative URLs into absolute URLs is 
high. This creates potential for conflict and/or multiple IDs.
* APIs may be available on different endpoints (URLs). Depending on the 
endpoint, that would create different IDs. That is not desirable. For a 
realistic example, a dev uses a small npm lib to parse Problem errors, 
and the lib correctly resolves the relative URI in "type" into absolute 
URIs. The dev treats errors based on these these types with absolute 
URIs. He and QA are testing against a dev or staging server and they do 
not know or realize that the production server will have a different API 
endpoint URL. So, it works in testing, but fails in production. Using 
relative URI for "type" is setting up for such a problem.
I would recommend to either 1) mandate absolute URIs, or alternatively 
to 2) define the ID as free-form generic string. In the latter case, 
relative URLs would not be resolved, but everybody would use them as 
strings - which is what likely happens in reality anyways.

I recommend to
replace: ```When "type" contains a relative URI, it is resolved relative 
to the document's base URI, as per {{URI, Section 5}}. However, using 
relative URIs can cause confusion, and they might not be handled 
correctly by all implementations.``` and the following paragraph with 
the example and the recommendation `it is RECOMMENDED that absolute URIs 
be used`,
with: ```Relative URIs are not allowed. That means that "type" MUST NOT 
be a number or simple string like "out-of-memory".```

2. Avoid a default "type"

Remove: `When this member is not present, its value is assumed to be 
"about:blank".`
Rationale: This would *require* (!) conforming clients to lump all 
non-typed errors together into one error. Better to leave this unspecced 
and allow the client to make sense of it.

3. Translation

Please clarify which party is expected to translate the message. Leaving 
this undefined can lead to problems in practice.
a) If both client and server try to translate, it can cause chaos.
b) Generic usage of a third party server API - which is the goal of an 
IETF spec - means that the client cannot possibly know all the error types.
c) Even if all error types were known, all clients would need to 
translate the same strings
d) The server may need to add new error types at any time.
(See also next point 4 for importance.)
Current spec: "title" is defined as `a short, human-readable summary of 
the problem type`, and "detail" is defined as `human-readable 
explanation specific to this occurrence of the problem` and it /allow/s 
localization of "title" by stating `it SHOULD NOT change..., except for 
localization`, but it's only an allowance.
Implication: Therefore, a client cannot rely on the error messages to be 
useful for the user. Given that for many errors, the only possible 
recourse is to show the error to the end user, translation is a real 
world problem. The client needs to rely on the error string to be useful 
for the user.
Recommendation:
`If error strings are translated at all, it is expected that the 
localization happens on the server side and the server sends localized 
strings for "type", "detail" and custom fields, based on the 
"Accept-Language:" HTTP header sent by the client. Rationale: The server 
is better suited to perform language-specific variable insertion in the 
"detail" field. It  allows for processing of errors from generic third 
party servers, and allows the server to add new error types without 
prior arranging with the client.`

4. Problem: HTTP header field and localization

The spec states: `The title and detail values MUST NOT be serialized in 
the Problem field if they contain characters that are not allowed by 
String; see {{Section 3.3.3 of STRUCTURED-FIELDS}}. Practically, this 
has the effect of limiting them to ASCII strings.`
I understand that the limitation to ASCII is imposed by prior existing 
specs. However, mandating error strings to be in English (which is what 
ASCII means in practice) is not very helpful for the purposes of this 
specification.
Importance: Errors strings need to be helpful for the user and allow 
them to correct the problem. If they are in a language that the user 
does not understand, they are unlikely to be helpful. This in turn 
leaves the end user frustrated. Messages that are potentially important 
for the end user MUST be translated into the user's language.

If it is not reasonably possible to convey in the HTTP header field, I 
would recommend to remove this transmission method entirely.
Alternatively, you could specify an escaping mechanism which allows for 
escaping of Unicode characters to be expressed with ASCII, e.g. a JSON 
string (RFC 4627 Point 2.5, Paragr. 2, "\u005C").
Recommendation: `The Problem: HTTP header field is a JSON string. 
Non-ASCII Unicode characters MUST be escaped, because HTTP Headers 
require ASCII.` (This sentence probably would need more tweaking.)


Thank you for consideration of these issues. I think addressing these 
issues would prevent serious problems in everyday usage of this spec and 
harden it.

That said, I am very happy that you are addressing error reporting in 
HTTP APIs.

Greetings,

Ben


Am 20.10.22 um 15:24 schrieb The IESG:
> The IESG has received a request from the Building Blocks for HTTP APIs WG
> (httpapi) to consider the following document: - 'Problem Details for HTTP
> APIs'
>    <draft-ietf-httpapi-rfc7807bis-04.txt> as Proposed Standard
>
> The IESG plans to make a decision in the next few weeks, and solicits final
> comments on this action. Please send substantive comments to the
> [e-mail]  mailing lists by 2022-11-03. Exceptionally, comments may
> be sent [e-mail]  instead. In either case, please retain the beginning
> of the Subject line to allow automated sorting.
>
> Abstract
>
>
>     This document defines a "problem detail" to carry machine-readable
>     details of errors in HTTP response content and/or fields to avoid the
>     need to define new error response formats for HTTP APIs.
>
>     This document obsoletes RF7807.
>
> Discussion Venues
>
>     This note is to be removed before publishing as an RFC.
>
>     Source for this draft and an issue tracker can be found at
>     https://github.com/ietf-wg-httpapi/rfc7807bis.
>
>
>
>
> The file can be obtained via
> https://datatracker.ietf.org/doc/draft-ietf-httpapi-rfc7807bis/
>
>
>
> No IPR declarations have been submitted directly on this I-D.
>
>
>
>
>