Draft: draft-ietf-httpapi-rfc7807bis

Commentary: Pulling this conversation out of : The current spec allows any type URLs to be used , and there 's no strong requirement that they link to documentation , it 's just encouraged . As an API client , it can be useful to be able to automatically find human - readable documentation relevant to an error response . Right now , the only way to do that is to dereference every type URL to see if it goes to a documentation resource , but a ) that 's discouraged by the spec ( type URIs should not be dereferenced automatically ) and b ) it 's not very efficient for anybody involved . As an example , Zolando 's specify that : All their API responses use absolute path types to deal with this , like , which intentionally go nowhere . This is allowed by our current spec , but makes life difficult for those of us who want to automatically find documentation from arbitrary problem detail responses . It would be useful to provide an explicit way to link to documentation in these cases , or to make it clear that no documentation is available . 
 With identification using URIs , you never quite know if it is a document or just a reference to a concept . Any person that followed httpRange-14 back in the days knows that this is hard . That said , the scenarios are multiple : only relies on expanding a uri to its full form ( from a basue uri for any uri ) , and checking it against a known value i learn anything from it , which is a " follow your nose " first principle : click on it , see if anything comes out If you were to add a " documentation " uri , i have no more guarantee that anything usefull will come out of it rather than following my nose to the original type , so I 'm not sure I m gaining a lot from a predictability perspective . If the main operator is human , then a documentation URI would only make sense because it overrides the main URI , which would only be done if said URI is not in control of the operator that published said URI . This seems unlikely to me , but I could see a scenario where you want , on your own API , to provide your own documentation for that above and beyond from the one that would be provided by the provider of that error . I 'm not sure what i think about that capacity , to say that " in our realm , we do n't do things the way they said , we got our own " . It 's an open question for me . If the main operator is a machine , then just a URI seems insufficient , especially as the override i mentioned above would be needed per type of automate - able documentation one could retrieve . 
 In that case , I wonder if a  header - with maybe ? - would be a better way of achieving that ? That way the actual problem payload does n't change just because some server wants to indicate that human - readable documentation about the problem exists somewhere different to the provided URI . 
 jumping in to hopefully make some progress with this : " automatically " following type links ( as mentioned by is n't a great idea , since this may cause the well - known problem of overwhelming the server of the type URI . that 's why RFC 7807 says that " Consumers SHOULD NOT automatically dereference the type URI . " instead of adding a specific " hint " , we could add language saying that if you want your type URIs not to be dereferencable , just create them that way , for example by using URNs ( or similar URI schemes ) . that way , we could one the one had provide guidance for those who want to create dereferencable URIs ( make them absolute ) and for those not wanting dereferencable URIs ( do not use relative URIs but instead use URI schemes that have no associated dereferencing mechanism , such as URN URIs ) . 
 that way , we could one the one had provide guidance for those who want to create dereferencable URIs ( make them absolute ) and for those not wanting dereferencable URIs ( do not use relative URIs but instead use URI schemes that have no associated dereferencing mechanism , such as URN URIs ) . So , what if I create a problem type that I originally intend not to be deref'd , but down the road I need it to be ? It seems to me that the harm in always using dereferenceable URLs is pretty minimal / manageable -- who try will get 404 's ( for HTTP URLs ) name ownership is a thing ( for schemes based on DNS ) So an alternative would be to recommend using HTTPS URLs in most cases , with a proviso that sometimes they wo n't be resolvable ( something a person can discover at their convenience ) , and that for standard / widely - used codes , a HTTP URL that 's stable ( possibly provided by IANA , as per ) is wise . Related to . 
 We can recommend this , but it seems likely that most problem types will still intentionally not be resolvable , unless it 's a hard requirement . The Zalando style guide specifically encourages that it should do so , and discussion elsewhere - it seems that API developers ( for some good reasons , e.g. uncoupling type ids from doc URLs ) want to use unresolveable type URLs , independent of their documentation URLs . As a tool author , that means I 'm going to have to automatically dereference every problem details type URL every time I receive such a response . That 's not great for anybody . I want to automatically find a working URL for problem documentation , every time a problem is received . In my case , I 'm working on an HTTP debugger where that 's especially relevant , but you can imagine many other use cases , e.g. in low - level libraries or clients , perhaps an HTTP library that throws clear friendly exceptions to help with debugging every time it receives a problem details response , something like : The problem is in the last line . If that goes to a 404 ( likely to happen in many cases ) it 's a very poor user experience for the end developer looking at their error logs , who 's just been told that it 's working documentation . Tools / libraries will reasonably want to avoid that experience as much as possible - the only current way to do so is to dereference every problem URL when it 's received , or to never try to link to documentation at all . If this is a use case we just do n't want to support in this RFC then that 's not totally unreasonable , and we could just close this . It seems like we 're very close to machine - discoverable problem documentation here though , and personally I 'd find that very useful . This is another separate good reason why imo it 'd be useful to have a explicit and independent way to link to problem details documentation from a response ( e.g. a link header , a separate field , etc etc ) 
 Here 's an interesting detail . If there was some way to determine that a problem URI was resolvable , and it resolves to a redirect then what does that mean ? I ask this because the comment I was originally going to make was about dead documentation links . I could make a problem URI today that is resolvable , but there 's no guarantee that it will still be resolvable in the future . Or , worse , it might just resolve to the wrong thing . And that then got me thinking about other ways that URIs can resolve to the wrong things , and redirects seems a particularly awkward one . I would assume that it does n't mean anything , and that the URI as written in the payload is the one to use . But equally , I can see an argument that two different URIs that both resolve as redirects to the same thing could be considered as the same problem , and that just makes life awkward . 
 Performing HTTP redirection from the URI to documentation is actually , since what 's used in is supposed to be a stable identifier , while the URI of a documentation site may be generated by a CMS and thus probably ca n't be considered stable . I 've never even considered that a URI comparison implementation could perform an HTTP request against the two URIs and see whether they , after HTTP redirection and whatnot , resolve to the same URI . Using resolvable URIs that perform HTTP redirection as identifiers is common . The whole of does it , for instance : redirects to . The former is the canonical identifier , the latter is the documentation about the identifier . 
 Whether or not it resolves to a redirect does n't change the problem identified by the type URI . If folks believe otherwise , please open a separate issue . I see what you 're saying regarding tool user experience . I 'm not against this , I could see us adding a member with a boolean value whose semantic is ' here 's a hint that the type URI is resolvable ' ; I could also see us adding a member with a separate URI for documentation . However , two things come to mind : if the problem says that the URL is resolvable , it still might not be ( e.g. , network failure , server - side issue , etc . ) . problems are going to omit this signal even when the URL is resolvable -- either because they do n't know about the signal , or they do n't care . Both of these reduce the quality of the information that the signal conveys . What I think we need to establish is whether it still conveys enough information to be worth the extra effort and complication . If we do n't have this sort of signal , I think a tool such as the one you 're talking about will need to present it as something like : Alternatively , you could attempt to resolve the URI and then cache the result , avoiding the need to make a request for every problem instance . To facilitate that , it might be interesting to put some bounds on how cacheable these type URIs are ... Either way , we should qualify the ' automatically ' prohibition against resolving the URI to make it applicable to runtime resolution , not debug time . Thoughts ?  I find that an often under - appreciated aspect of APIs is the cognitive load they place upon users ; if there are too many options , they 're less likely to use what 's available well . 
 One other aspect of this that we have n't discussed : if we 're talking about adding a new member that 's valid and standard across all problem objects , it violates this statement in 7807 : So if we decide that this is a must - have , we 'll need to either define a new media type for problem types , or convince ourselves that defining such an extension wo n't break currently deployed extensions ( without being able to know their breadth ) . 
 Discussed in 111 : default resolvable is good . Not a strong motivation for a ' does n't resolve ' flag ; close with no action ( except perhaps prose ) . 
 Sounds good to me . If we can strengthen the spec from gentle encouragement to " if the type is dereferenceable , it SHOULD resolve to documentation " ( or similar ) and qualify the " Consumers SHOULD NOT automatically dereference the type URI " text as , then my use case should work reliably with no extra fields required , which would be great . This then ties into & : we should give a clear recommendation for an alternative , for those who do want explicitly non - resolvable types . Does all this apply the same to ? That currently does n't state a position on this at all : " It may or may not yield further information if dereferenced " 
 would n't that be odd ? the type URI probably mostly will be used for comparing to some known type URIs . the instance URI on the other hand probably most often will provide access to info analyzing the specific reasons for the problem , no ? 
 It 's just that the same ambiguity applies : is intended as a link to a resource the receiver should visit for more information about that specific transaction , or intended only as an opaque identifier ? It 's quite plausible that the situation is n't the same as , and that 's OK . It 's not really as important for tooling AFAIK ( I imagine tools are all more likely to be interested in linking to human - readable documentation than the failing resource itself , which could be anything ) and I do n't have a strong opinion either way . If we do think both should be treated similarly ( i.e. both should be resolvable by default ) then that 's neat and we can use consistent recommendations throughout . If not then that 's fine too - we just need to make it clear that they 're different ( and if this is the case , I think the current text does that OK ) . Either way I think an answer for as well as would be nice , so that it 's clear what to do if you want either to be explicitly not resolvable , but that 's just offering an optional suggestion , not a constraint . 
 See proposal in - thoughts ? 
 Good improvement , for me , thanks !
The "type" member is a JSON string containing a URI reference RFC3986
that identifies the problem type.
This specification encourages that, when dereferenced, it provide
human-readable documentation for the problem type (e.g., using HTML
HTML5).  When this member is not present, its value is assumed to be
"about:blank".
When "type" contains a relative URI, it is resolved relative to the
document's base URI, as per RFC3986, Section 5.  However, using
relative URIs can cause confusion, and they might not be handled
correctly by all implementations.  For example, if the two resources
"https://api.example.org/foo/bar/123" and "https://api.example.org/
widget/456" both respond with a "type" equal to the relative URI
reference "example-problem", when resolved they will identify
different resources ("https://api.example.org/foo/bar/example-
problem" and "https://api.example.org/widget/example-problem"
respectively).  As a result, it is RECOMMENDED that absolute URIs be
used in "type" when possible, and that when relative URIs are used,
they include the full path (e.g., "/types/123").
Consumers MUST use the "type" URI (after resolution, if necessary) as
the primary identifier for the problem type.  Consumers SHOULD NOT
automatically dereference the type URI.
The "type" member is a JSON string containing a URI reference RFC3986
that identifies the problem type.  Consumers MUST use the "type" URI
(after resolution, if necessary) as the primary identifier for the
problem type.
When this member is not present, its value is assumed to be
"about:blank".
If the type URI is a locator (e.g., those with a "http" or "https"
scheme), dereferencing it SHOULD provide human-readable documentation
for the problem type (e.g., using HTML HTML5).  However, consumers
SHOULD NOT automatically dereference the type URI, unless they do so
in the course of providing information to developers (e.g., when a
debugging tool is in use).
When "type" contains a relative URI, it is resolved relative to the
document's base URI, as per RFC3986, Section 5.  However, using
relative URIs can cause confusion, and they might not be handled
correctly by all implementations.
For example, if the two resources "https://api.example.org/foo/
bar/123" and "https://api.example.org/widget/456" both respond with a
"type" equal to the relative URI reference "example-problem", when
resolved they will identify different resources
("https://api.example.org/foo/bar/example-problem" and
"https://api.example.org/widget/example-problem" respectively).  As a
result, it is RECOMMENDED that absolute URIs be used in "type" when
possible, and that when relative URIs are used, they include the full
path (e.g., "/types/123").
When "instance" contains a relative URI, it is resolved relative to
the document's base URI, as per RFC3986, Section 5.  However, using
relative URIs can cause confusion, and they might not be handled
correctly by all implementations.  For example, if the two resources
"https://api.example.org/foo/bar/123" and "https://api.example.org/
widget/456" both respond with an "instance" equal to the relative URI
reference "example-instance", when resolved they will identify
different resources ("https://api.example.org/foo/bar/example-
instance" and "https://api.example.org/widget/example-instance"
respectively).  As a result, it is RECOMMENDED that absolute URIs be
used in "instance" when possible, and that when relative URIs are
used, they include the full path (e.g., "/instances/123").
When "instance" contains a relative URI, it is resolved relative to
the document's base URI, as per RFC3986, Section 5.  However, using
relative URIs can cause confusion, and they might not be handled
correctly by all implementations.
For example, if the two resources "https://api.example.org/foo/
bar/123" and "https://api.example.org/widget/456" both respond with
an "instance" equal to the relative URI reference "example-instance",
when resolved they will identify different resources
("https://api.example.org/foo/bar/example-instance" and
"https://api.example.org/widget/example-instance" respectively).  As
a result, it is RECOMMENDED that absolute URIs be used in "instance"
when possible, and that when relative URIs are used, they include the
full path (e.g., "/instances/123").