RFC 7807: "Problem Details for HTTP APIs" — serve REST error responses as application/problem+json

Any new inclination about how to proceed here?

Crell's new library might be a candidate for this? https://github.com/Crell/ApiProblem

I wasn't really thinking of this issue when I wrote it, but yes, that would make using api-problem dead simple. (I wanted to use it for a project at work, and just to see if I could do it.)

Proposal: Let's use ApiProblem, including the library linked above, and call it a day. Yay/nay?

I just ran into a situation where an actual ApiProblem implementation including a bridge to symfony validator would've been really helpful. It should be easy to respond to a request with a list of validation violations.

Edit: The situation in which I needed this (although it might be obvious) was for implementing node entity forms in a React frontend.

ApiProblem is good, but the spec is still not finalized. It's in draft 7 now, I think. I just updated my library for it a few weeks ago. :-)

I'm not against using it, but I want to be cautious about API stability. I'm not sure if we want to lock ourselves into a draft spec that may change for the next however many years of D8's life.

That said, a contrib module that tosses ApiProblem in place would be quite simple to write. I did so for a Symfony project last month and it took less than a day. That may be the safer option from an API stability standpoint.

Discussed with Klausi in IRC. We'll go with a contrib module for now. Once ApiProblem settles down as a spec we can look at moving it into core in a later 8.x release or in D9.

I hadn't heard of application/vnd.error+json somehow, despite lots of work around HAL resources. The post example looks a little more obscure from a DX perspective, and I do not see any benefits not present in api-problem except for more explicit direction on how to handle multiple errors.

REST should use one problem format, so a format that mostly makes sense to HAL-focused eyes would be out of place in some cases.

Api-Problem is now a finalized spec, and my library (linked above) has been updated for the final RFC in the 2.0 version. There will be other features added to the library in time but for now all the core capabilities are there. (Unless we want to move it to be evolvable, a la PSR-7?)

https://tools.ietf.org/html/rfc7807 was ratified in March 2016.

Note that #2808233: REST 403 responses don't tell the user *why* access is not granted: requires deep Drupal understanding to figure out already helped improve our REST error responses a lot. And thanks to #2737719: EntityResource: Provide comprehensive test coverage: for every entity type, every format, every method, we're thoroughly testing every single one of our responses.

It's now more feasible than ever to adopt this. The main question is: do we want this?

Also, I wonder if #2856110: [PP-1] Expose entity validation errors in a machine readable REST API: is basically a duplicate of this? It focuses on entity validation errors. But if we're going to do that, we should just adopt this RFC right away, rather than first creating our own format, and then causing disruption for REST clients by moving from HEAD's validation error responses (which are basically unparseable plain text) to the custom JSON format there and then finally to the format defined by RFC 7807.

Updating title to match the RFC.

In #14+#17, I updated the issue title to choose RFC 7807. I had missed for a moment that the Is said:

There seem to be two different approaches which are gaining traction, api-problem from the IETF and vnd.error from the HAL community.

Well, since then, a clear winner emerged: RFC 7807/application/problem+json from the IETF (ratified in March 2016) — application/vnd.error+json from the HAL community was last updated on September 9, 2014.

So, let's be more clear/explicit.

… and the title already was explicit/clear, but the IS was not yet.

Rather than writing an entirely new IS, let's copy/paste the one from #2811483: Adopt Problem Details RFC for REST Error Responses, which is basically a 100% duplicate of this issue. Many thanks to @Grayside (please credit him!) for writing that.

I'm wondering whether we can somehow shortcut some of the list entries explained in issue summary.
We have a concrete problem out there and some of those would require quite a lot of work:

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

I'm wondering for example whether we could for now just use a non existing URL for the errors?

I'm wondering for example whether we could for now just use a non existing URL for the errors?

+1, we do the same for link relation types: see core/core.link_relation_types.yml, specifically the top of the file, where it says:

# Drupal core's extension relation types.

I wanted to create a document on drupal.org at least starting, but then I realized, you need some special permission for that :(
I'll continue with this document maybe tomorrow or on the weekend.

👍

Since this is a specific format, how is this going to be negotiated? I worry about formats that have their own spec for errors being trampled by this one.

I miss in the IS in what formats this is going to be triggered. Does this only apply to our JSON format in core? Does also apply to HAL? Is this going to apply everywhere and it's the responsibility of any other format to override it? I assume it's the latter, since we already have a format for errors and that's what we're trying to replace.

We're conflating unopinionated / unknown formats with an opinionated format for errors. That may be good, but we need to aknowledge it as a feature.

@edgab has opened a JSON API support request/documentation issue specifically about how to deal with the currently implemented validation error message structure, and how to actually use that in a client application.

FYI: The jsonapi.module effectively already implements this, because the JSON:API spec has absorbed the relevant portions from RFC7807. See https://jsonapi.org/format/#error-objects. Even the language is lifted from RFC7807, for example:

RFC7807

     "title" (string) - A short, human-readable summary of the problem
      type.  It SHOULD NOT change from occurrence to occurrence of the
      problem, except for purposes of localization

JSON:API spec

title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

That doesn't change anything here, but I just wanted to call it out explicitly that this issue applies only to rest.module.