search

ietf-wg-httpapi / rfc7807bis

Revision of RFC7807: HTTP Problem Details
Other
20 stars 8 forks source link

Resolveability text #63

Closed mnot closed 1 year ago

mnot commented 1 year ago

From Carsten:

The specification is a bit wobbly on whether type URIs should be resolvable -- it explains the possibility, immediately explains an evolvability problem with non-resolvable type URIs, and then later has a SHOULD for being resolvable.

dret commented 1 year ago 
The specification is a bit wobbly on whether type URIs should be
resolvable -- it explains the possibility, immediately explains an
evolvability problem with non-resolvable type URIs, and then later has
a SHOULD for being resolvable.

in my mind, advocacy for resolvable URIs could be less pronounced. we have made a choice to use type URIs as identifiers, and describing all the things that they could also be might be more confusing than it is helpful.

mnot commented 1 year ago

Right now we say:

A non-resolvable URI ought not be used when there is some future possibility that it might become desirable to be able to resolve the URI. For example, if an API designer used the URI above and later adopted a tool that resolves type URIs to discover information about the error, taking advantage of that capability would require switching to a resolvable URI, creating a new identity for the problem type and thus introducing a breaking change.

and then:

A problem's type URI SHOULD resolve to HTML {{HTML5}} documentation that explains how to resolve the problem.

I'll make a small change to align this a bit better. I don't think we should revisit / weaken this, it'd just involve more going around. Let's respect the consensus we found.