Add problem types

[RaySinnema]

The errors that an API can return should also be documented. I’m talking specifically about the error URIs that would be the values of the type property in Problem Details for HTTP APIs, but I guess the same sort of information would be helpful to clients even if the server doesn’t follow Problem Details.

[EMC ECD's Cloud Content & Collaboration Platform publishes problem types as part of its API jar in the form of constants that clients can use to compare against the problem types in the response body. This is similar to how it publishes its billboard URI, extension link relations, XML namespace URIs, etc.]

Should we add a <problem-types> element to RADL to capture this information?

Maybe something like the following:

problem-types = element problem-types { documentation*, problem-type* }
problem-type = element { problem-id, documentation* }
problem-id = attribute type { xsd:anyURI }

Or maybe we don't want to enforce the use of URIs for problem types:

problem-types = element problem-types { documentation*, problem-type* }
problem-type = element { name, documentation* }

[jonathanrobie]

Historical note: we had problem types in an earlier version, and removed them. At the time, we were trying to simplify RADL, and felt that the draft was not widely used. I don't know if that has changed, I notice that the draft has recently expired.

At this point, I would rather look for ways to simplify RADL than ways to add features unless there is a clear need for them. This doesn't feel like a MUST to me, we could easily add it later if need be.

[RaySinnema]

The issue is that 400 Bad Request isn't enough information for a client to recover from an error, so a server needs to provide more detail in the form of some sort of error codes. These error codes must be documented so that clients can recognize them.

Whether the error codes take the form of the Problem Details draft, Mason's @error, or something else isn't all that relevant.

[jonathanrobie]

Yes, we should add something, but it should be usable for the various approaches people take when reporting errors in REST APIs. This summary seems useful:

http://soabits.blogspot.dk/2013/05/error-handling-considerations-and-best.html

[gentlewind]

The REST problem is defnitely needed with respect to the RADL completness. URI problem type is probably the right design but I am afraid most on-premise REST APIs do not design it in this way. So a loosely constrained problem type may be a preferrable choice. The priority to resolve this issue is another problem we'll need to discuss.

[RaySinnema]

So it seems that the minimum useful construct is:

errors = element errors { documentation*, error* }
error = element error { name, documentation* }

We could simply show this in a table in the client documentation.

Does anyone disagree?

[jonathanrobie]

+1 on this minimum construct.

[gentlewind]

+1