Adopt Problem Details RFC for REST Error Responses

Problem/Motivation

Existing error messages in Drupal REST responses are one dimensional—a string contextualized by an HTTP status code. This is limiting in several ways:

• It is very difficult to provide adequate depth of insight into an error via a one-line message.
• Categorization of "sub-types" below the level of status code and above the specific error message is difficult, inhibiting ease of troubleshooting research
• The response is too basic to facilitate more advanced integration around fault tolerance and error handling UX.

Proposed resolution

RFC 7807: Problem Details provides a description for structured XML or JSON responses that facilitate greater detail in the error messages.

A few thoughts on some of the available properties:

• type can link to documentation pages on Drupal.org about the error category, driving developers to a landing page to help facilitate research.

title can be made high-level and unique by type, to facilitate googling without the kinds of identifiers, URIs, and file paths that are unique to an environment.

• instance might be used in the future for more targeted knowledge base building. With some coordination, dedicated URLs or sections within the type URL could be linked to for more specific delving.

Example

{
  "type": "<url>",
  "title": "Access denied to content",
  "status": 403,
  "details": "Currently authenticated user lacks permission to view content on this site."
  "instance": "<url>#access-denied-to-content",
}

Furthermore, problem-specific extensions allow additional properties to be added. There are many future enhancements that might be considered from there.

Remaining tasks

1. Decide from a product standpoint if this is a good direction for the Drupal REST implementation
2. Create a facility to support message output in the application/problem+json or application/problem+xml format.
3. Perform an initial survey of REST error messages to determine categories.
4. For each error category, find or prepare a documentation page to server as the type URL.
5. Convert errors thrown in the course of REST responses to be handled by the new error response mechanism.

Out-of-initial-scope

• Handling multiple problems per error response
• Coordinating documentation for error "instance" property
• Adding flags to tailor the error response based on maintenance mode or other site states

User interface changes

REST error responses will change in structure and Content Type. Code which parses and uses the existing structure will break, though backwards compatibility might be preserved by using existing properties as "extensions" per the RFC.

API changes

New representation for errors will likely result in API additions. Changes in error handling might result in API changes to add additional parameters to some exceptions.

Data model changes

None.