search

w3c / wot-profile

Web of Things (WoT) Profile
http://w3c.github.io/wot-profile/
Other
16 stars 8 forks source link

Clarify RFC7807 Problem Details Format constraints #142

Closed mlagally closed 2 years ago

mlagally commented 2 years ago

RFC7807 has a couple of options that should be clarified in the Profile. Open questions include:

benfrancis commented 2 years ago

@mlagally wrote:

  • Should we permit XML formats?
  • Should we permit HTML strings?

These alternative representations are included in appendices, the introductions of which say:

Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary format convention. Such APIs can express problem details using the format defined in this appendix.

an API that uses HTML [W3C.REC-html5-20141028] might want to also use HTML for expressing its problem details.

The introduction to section 5.2 Protocol Binding of WoT Profile says:

This section defines a protocol binding which describes how a Consumer communicates with a Web Thing [wot-architecture] using JSON [JSON] payloads over the HTTP [HTTP11] protocol.

It therefore seems quite self-explanatory to me that since the Core Profile protocol binding uses JSON, these sections do not apply and therefore the default JSON serialisation of Problem Details should be used.

Should we permit "about:blank"?

Yes, I can't think of any reason to specifically exclude this part of the specification for WoT. As I understand it, it allows for the type member to be optional in cases where the error has no additional semantics beyond that of the HTTP status code.

include retryAfter ?

I can't find this string in RFC 7807, what are you referring to?

It was originally suggested to use the Problem Details format for error responses since this is already used by the Directory Service API in WoT Discovery.

@farshidtz I know that there's some discussion about defining standard WoT specific error types (so that they don't all have to be implementation specific), but other than that do you see the need for any clarifications here? It seems fairly straightforward to me.

farshidtz commented 2 years ago

Please refer to https://github.com/w3c/wot-discovery/issues/150 where the rationale behind the use of about:blank as type in the current discovery spec is explained.

benfrancis commented 2 years ago

Please refer to w3c/wot-discovery#150 where the rationale behind the use of about:blank as type in the current discovery spec is explained.

OK, so it seems like to be consistent we should allow about:blank (at least until there are WoT specific error types).

Until that is the case, implementers could also define implementation-specific problem types with their own URLs which could at least dereference to a human-readable explanation of the error message as is recommended by RFC7807.

I personally think it's pretty self-explanatory that the HTTP+JSON protocol binding should use the default JSON serialisation of the Problem Details Format, but I've created a PR which makes it explicit.