Draft: draft-ietf-httpapi-rfc7807bis

Commentary: Note that the recommendation regarding a URI prefix for registered values is subject to other discussions . 
 my reading of RFC 7807 is that the vanilla status codes do not need types and this is where about : blank is explicitly recommended ( if somebody does not want to simply omit the type URI , which also is allowed ) . i think this is how the RFC does it and i do n't think we even have the option to change this and to now recommend specific type URIs for vanilla problem reports . 
 ( 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 header on a 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 , whereby all clients that see a link relation of , for example , or know what they mean regardless of the API that produced them . 
 Unlike relation type name ( or 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 ( 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 . 
 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 . 
 There are a couple of ways to go here : an IANA registry of problem types , much as for link relations . 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 ) is n'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 ) . Note that 7087 allows relative URIs in the field , we could n't use bare tokens like link relations do . However , if folks wanted " neutral " URIs that did n't reflect a particular vendor , we could easily mint URIs in a common name space like or 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 ) . 
 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 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 in these cases - it does n'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 ) 
 The RFC recommends that 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 . 
 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 " . :) 
 For " standard " problem types , would folks be willing to stomach the form ? That 's likely the most permanent , easy way to do it . Using is also possible , as would be . 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 . That might make some of the URN folks unhappy , though ; would have to try to find out . 
 I think we need to before we can decide on the format . 
 I guess the form we go for depends on some other things . If we decide ( per as says ) that the value should be a URI , and that it should resolve to documentation , then something like 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 idea - I currently always use 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 in the first place . Also , ( and I might be missing things here ) it seems that the only real benefit of over is in the length of the string , which is n't a huge deal - it 's a saving of 17 characters . 
 In the meeting , folks seemed to pretty strongly lean towards an IANA registry with some bar to entry ( TBD ) . 
 See for a proposal . 
 thanks for , i like it , but my concern is a bit that if we have a registry , would n't it make more sense to suggest using a URN scheme or a URN pattern ( was proposed above ) for registered type ? the registry specifically is there for discovery , so we do n'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 . 
 see discussion in . 
 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 . 
 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 : 
 Discussed in 111 : no strong feelings about URI scheme ; a bit of preference for urn . 
 I 'm going to go ahead and merge as is ; we can address the URI scheme part as our thinking on that develops . 
 i like it , but i am wondering if proposing a URI that points at the IANA registry is n't potentially a risky thing to do ( in terms of driving traffic to that URI ) . i personally like the idea of a dedicated URN scheme better , as we will now have the registry to aid with discovery .
This specification defines the HTTP Problem Type registry for common,
widely-used problem type URIs, to promote reuse.
Registration requests are reviewed and approved by a Designated
Expert, as per RFC8126, Section 4.5.  A specification document is
appreciated, but not required.
When evaluating requests the Expert(s) should consider community
feedback, how well-defined the problem type is, and this
specification's requirements.  Vendor-specific, application-specific,
and deployment-specific values are not registrable.
Registrations MAY use the prefix "https://iana.org/assignments/http-
problem-types#", and are encouraged to do so when a stable, neutral
URI is desirable.
See the registry at https://iana.org/assignments/http-problem-types
[1] for details on where to send registration requests.
This specification registers one Problem Type, "about:blank".
Please create the HTTP Problem Types Registry, as specified in
registry, and populate it with "about:blank" as per blank.