Multi-status responses (partial success in particular)

#1

Continuing the discussion from https://github.com/json-api/json-api/issues/787

I’m trying to determine the convention for a multi-status return code for an operation with multiple success and failure sub-operations. In this particular case a request is made for a collection of performance metrics, each of which spawns an individual request that may succeed or fail. The accumulated result is then returned in the API response.

I’ve been poking around the return code 207 as per https://tools.ietf.org/html/rfc4918#section-13 but this doesn’t appear to be recommended because of WebDAV not being part of core HTTP.

The conventions outlined in the JSONAPI spec seem to handle multi-failure well, but I don’t see a great way to handle a partial success.

#2

I suspect the main reason the spec doesn’t yet define conventions for partial success is that we don’t yet support bulk operations. I.e., a request is always supposed to operate on only one resource at a time, and for operations on single resources, it’s simpler if the operation must fail or succeed completely. When we standardize the extension system + the bulk extension, support for things like this may get better. But, until then, I think you should try to restructure your resources so that one response code is sufficient. Again, if you post more about your particular data model, we can help further.

Cheers,
Ethan

#3

we have similar case as we need to return, in addition to success data, some “business errors” or “warnings messages” (not only for bulk operations). we are thinking about:

{
“meta”:{
“warnings”: [{
“code”: “723119”,
“source”: { “parameter”: “promo” },
“title”: “ignored”,
“detail”: “overridden by default value”
}]
},
“data”:{…}
}

warning object has same structure as for error object

your thoughts!

Add warning section in JSON API spec
Handling empty included results due to authorization
#4

a request is always supposed to operate on only one resource at a time, and for operations on single resources, it’s simpler if the operation must fail or succeed completely.

What about the case where a client makes a request with an include parameter and the main / core request succeeds but the associated include fails (possibly different services are responsible for fulfilling the requests, so the main service could be up and the associated service down)?

Should the API respond with a 503 error and ask the client to try again, and suggesting omitting the include?
Should the API respond with a 206 and serve the response as if the include had not been used (possibly adding some meta information to explain the reason to the client)?

#5

Hi @jlangley

I may have misread the specification, but I don’t see where a client can make a request with included ?

If my above assumption is correct the entire request should fail even if a relationships key is present, because it is still a single atomic request, although your server may indeed need to make multiple requests or database records. The point here being that the uniform interface alleviates the need for a client to know about such specific details.

#6

I may have misread the specification, but I don’t see where a client can make a request with included ?

http://jsonapi.org/format/#fetching-includes

If my above assumption is correct the entire request should fail

This feels a bit fragile, but maybe whether that matters depends on the particular client

#7

Aah I see, I was thinking in terms of modifying resources.

IMHO I think it should still fail completely, your fail reason will be that fetching the requested include could not be completed (because that is the request the client made), a client could still make a modified request to get the data that is available, for example not adding the include parameter

Handling empty included results due to authorization
#8

I agree with @A-Helberg. If an include isn’t available, the request needs to fail completely. Sending a 206 would be inappropriate, as 206 only applies with the Range header, which is it’s own thing. I think 503, as @jlangley suggested, would be fine, and the error object could include info about trying again without the ?include

#9

Although this does not address the multiple response status codes, I created some documentation on how I’m dealing with partial success in the Drupal implementation.

I hope this is useful to someone.