Repository of common Problem types

[sazzer]

(I'm not sure if this is the correct place to propose this, so apologies if not!)

As RFC-7807 gains wider-spread adoption, it is becoming the case that more and more APIs are returning effectively the same problems with different values for the fields. This makes it difficult to work across different APIs, because you need to understand that different problems from those APIs actually mean the same thing.

Common examples that you might expect to see include:

• Resource not found
• Authentication failure
• Optimistic lock failure (e.g. the If-Match header on a PUT request has the wrong value)
• Request validation failure

It seems that it would be useful to have a repository of these common problem types that can then be reused across APIs, so that ideally these common situations can be handled in the exact same way on the client.

Effectively the same idea as the standard list of Link Relations, whereby all clients that see a link relation of, for example, self or item know what they mean regardless of the API that produced them.

[sdatspun2]

Unlike relation type name (self or item), problem type` is a URI in 7807. Is there any other example of a repository of entities where each entity is uniquely addressable?

Also, I am working on API for such a repository https://github.com/sdatspun2/error-catalog-service (When you read, replace "Error Type" with "Problem Type" and "Error Catalog" with "Problem Type Repository"). I would like to submit it here to evolve it if there is interest.

[sazzer]

My concern here, and why I raised this ticket, is less to do with APIs using the same value for different meanings, and instead to do with APIs using different values for the same meaning. Mostly it makes API design that bit easier if there is a well known value to use for what you're trying to indicate.

…

On Sun, 31 Jan 2021, 17:20 Sanjay Dalal, ***@***.***> wrote: Unlike relation type name (self or item), problem type` is a URI in 7807. Is there any other example of a repository of entities where each entity is uniquely addressable? Also, I am working on API for such a repository https://github.com/sdatspun2/error-catalog-service (When you read, replace "Error Type" with "Problem Type" and "Error Catalog" with "Problem Type Repository"). I would like to submit it here to evolve it if there is interest. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#7 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAQEGB7BDO32QVU2OTYXDTS4WGNVANCNFSM4WYQPZJA> .

[mnot]

There are a couple of ways to go here:

1. Create an IANA registry of problem types, much as for link relations.
2. Create a publicly-coordinated informal repository (eg, in a wiki).

Because types are required to be URIs, avoiding conflicts (one of the main reasons to use a registry) isn't relevant; it would be more to aid discovery. If we wanted some sort of quality filter on it, we'd probably use an IANA registry, and would need a process around that (e.g., expert review, IETF review; see RFC8126 Section 4).

Note that 7087 allows relative URIs in the type field, we couldn't use bare tokens like link relations do. However, if folks wanted "neutral" URIs that didn't reflect a particular vendor, we could easily mint URIs in a common name space like urn:ietf:params:http-problems:foo or https://httpwg.org/http-problems/foo or something else.

P.S. Resource Not Found and Authentication Failure are already HTTP status codes -- 404 and 401, respectively (unless you mean non-HTTP auth in the latter case).

[sazzer]

P.S. Resource Not Found and Authentication Failure are already HTTP status codes -- 404 and 401, respectively (unless you mean non-HTTP auth in the latter case).

These are already HTTP status codes, but it's not unreasonable for APIs to want to always return a Problem response for any error. Sometimes it's easier to develop the server code that way (e.g. in Rust it's very verbose to have many different response types.) Sometimes it's easier to allow clients to always assume an application/problem+json response. Sometimes it's just that people like consistency. And actually the only real downside seems to be that the response payload is non-zero in size

Given that though, it means that people start to mint URIs for problem types that directly correspond to HTTP status codes. And, odds are, different people do it differently. That's a key example where some standard values would just make that a little bit easier. For example, I've started using values like https://httpstatuses.com/404 in these cases - it doesn't actually tell you anything more than the HTTP status code, but it means that the response body is always in a consistent format which just makes life that little bit easier in some cases. (I did consider a link to the appropriate section of RFC-7232, but that seemed a bit more awkward given that it would need a fragment in the URI)

[mnot]

The RFC recommends that about:blank be used in this situation. We intentionally did not have per-status-code values, because that would encourage developers to ignore the real status code, and because duplicating values at different layers is a vector for bugs and security issues.

[sazzer]

Ah - I'd totally missed that paragraph! That does make a lot of sense, especially when coupled with the absence of the "type" parameter mapping on to "about:blank". :)

…

On Thu, 4 Feb 2021 at 23:32, Mark Nottingham ***@***.***> wrote: The RFC recommends that about:blank be used in this situation. We intentionally did not have per-status-code values, because that would encourage developers to ignore the real status code, and because duplicating values at different layers is a vector for bugs and security issues. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#7 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAQEGAO2P4YQSS3XB73MOLS5MVBVANCNFSM4WYQPZJA> .

[mnot]

For "standard" problem types, would folks be willing to stomach the urn:ietf:params:http-problems:foo form? That's likely the most permanent, easy way to do it.

Using httpwg.org is also possible, as would be ietf.org. Some might complain that they (especially the former) are rooted in DNS, and therefore might not be stable over a long time scale.

Another option would be minting our own URI scheme, to make something like http-problem:foo. That might make some of the URN folks unhappy, though; would have to try to find out.

[asbjornu]

I think we need to resolve #11 before we can decide on the format.

[sazzer]

I guess the form we go for depends on some other things. If we decide (per #11 as @asbjornu says) that the value should be a URI, and that it should resolve to documentation, then something like https://httpwg.org/problems/foo might be better. But then, as you say, that means that URL has to remain stable for the foreseeable future.

Personally speaking, I'm fine with the urn:ietf:params:http-problems:foo idea - I currently always use tag:xxx,2021:foo for mine anyway - but it does mean that they are definitely not resolvable.

I'm less keen on the idea of a new scheme. It is obvious what's happening, but it does start to look like all problems must be in that scheme, which then potentially defeats the point of #11 in the first place. Also, (and I might be missing things here) it seems that the only real benefit of http-problem:foo over urn:ietf:params:http-problems:foo is in the length of the string, which isn't a huge deal - it's a saving of 17 characters.

[mnot]

In the meeting, folks seemed to pretty strongly lean towards an IANA registry with some bar to entry (TBD).

[mnot]

See #24 for a proposal.

[dret]

thanks for #24 , @mnot! i like it, but my concern is a bit that if we have a registry, wouldn't it make more sense to suggest using a URN scheme or a URN pattern (urn:ietf:params:http-problems was proposed above) for registered type? the registry specifically is there for discovery, so we don't have to use HTTP URIs which create the risk of tooling accessing those URIs and creating unnecessary load.
my personal preference would be to go the URN way (scheme or pattern) and maybe add a section on discovery, which would then point out these alternatives: if you use custom types, you have to think about discovery. if you think about registering types, then discovery is taken care of by the registry, so using a non-dereferencable URI may be the better option to choose.

[mnot]

@dret see discussion in #15.

[dret]

On Jul 19, 2021, at 07:27, Mark Nottingham ***@***.***> wrote: @dret see discussion in #15.

thanks for the pointer, i forgot about that one... i still think that using a URN is cleaner and more google friendly (seeing that automated dereferencing is not the goal here), but of course both options technically work. maybe this would be something useful to present as a choice to be made in the next meeting.

[dret]

just in case anybody is interested in a general discussion of why and how to use registries, here's something i wrote a while ago that discusses various aspects of the general pattern: https://datatracker.ietf.org/doc/html/draft-wilde-registries-03

[mnot]

Discussed in 111: no strong feelings about URI scheme; a bit of preference for urn.

[mnot]

I'm going to go ahead and merge as is; we can address the URI scheme part as our thinking on that develops.