REST API response in partial success

Question

I have an API which does some bulk processing task. Let's say it does naming of some resource.

I passed 7 request in bulk, out of which 5 updated successfully and 2 failed.

My question is how to handle the response. With HTTP I can't return both success and error at same time.

There is a HTTP code of partial success but I need to return individual response of all resource at once. Is there anyway we can do it?

Practically infinite ways. This is a design decision you'll need to make on your own, based on your particular situation. — Adrian, Aug 01 '17 at 16:19
This isn't a Go question at all, it's an HTTP/API question. You can handle this in countless ways, and the best one depends on your needs and possibly tastes. — Jonathan Hall, Aug 01 '17 at 20:02

score 26 · Accepted Answer · edited Sep 20 '22 at 10:32

26

You may use 207 MULTI-STATUS for http status: A Multi-Status response conveys information about multiple resources in situations where multiple status codes might be appropriate.

The default Multi-Status response body is a HTTP entity with a 'multistatus' root element. Further elements contain 200, 300, 400, and 500 series status codes generated during the method invocation.

You can have an array of response objects within the body of the response and those objects may have their own status codes

Example

HTTP 207

{
    "data": [
        {
            "message": "success",
            "resource": {
                "foo": "bar",
                "id": "1d1"
            },
            "status": 200
        },
        {
            "message": "Requested resource or subresource not found",
            "resource": null,
            "status": 404
        },
        {
            "message": "success",
            "resource": {
                "foo": "bars",
                "id": "1d2"
            },
            "status": 200
        }
    ],
    "metadata": {
        "failure": 1,
        "success": 2,
        "total": 3
    }
}

edited Sep 20 '22 at 10:32

Alexandre

1,132
1
10
21

answered Aug 01 '17 at 16:39

Sarath Sadasivan Pillai

6,737
29
42

@bandishankar please check this example, it does not cover all possibilities but serves as a basic sample – Sarath Sadasivan Pillai Aug 01 '17 at 17:41
2

how valid is this sample response? the [relevant RFC](https://tools.ietf.org/html/rfc4918#section-13) seems to indicate that the response is meant to be in XML format and follow a particular structure, which the sample response doesn't do. – quiram May 17 '18 at 16:43
The same spec suggests the default Multi-Status response body is a text/XML or application/xml. So `json` is valid as far as the content-type is `json` – Sarath Sadasivan Pillai May 18 '18 at 07:28
I have a situation where i need to add object created/updated as well as error object in the response. e.g. 2 entities created but 3 had issues. Does anyone have a example code which can help? – Saurabhcdt Dec 11 '18 at 09:40
@Saurabhcdt either at the same level as `data` you may have a `error` field and have error data there or use the same `data` field for both . In the example here you can find 2nd item in `data` is an error – Sarath Sadasivan Pillai Apr 26 '19 at 12:32
2

I've seen other answers to this same question that prefer to give a `200 OK` response for scenarios like this - however this answer seems to be the better answer. It's better designed, more logical, and informative. This way API client's don't have to do any logic for `200 OK` responses. Also most API management tools will track metrics per API response code and it's better informational purposes to track these separately. Example: you upgrade your API's database and now see a spike in "207" response codes in your API management tool. Now you know to investigate. – alex Apr 13 '21 at 15:10
Beware that this solution is valid for WebDAV. Most plain HTTP peers wont be able to make sense of such responses. And if you are going to support WebDAV you should support all of the spec and not only what you basically need. HTTP isn't the right protocol in terms of batch processing. I.e. a cache won't be able to update stored responses for affected "resources" of such a request. As such, I'd recommend NOT going this route unless you support WebDAV fully – Roman Vottner Sep 20 '22 at 20:49

REST API response in partial success

1 Answers1

Linked