Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?

Status

This extension was developed as part of the jsonapi module for Drupal.

Introduction

It is possible for a server to have mixed success and error responses when dealing with a single or multiple entities at once. For instance, when generating collections of resource entities there is a chance that the GET operation results in a partial success. That is because each entity can generate errors independently from the other. In such scenarios the server MAY respond to the request with a partial success response.

Servers and clients MUST negotiate support for and use of the Partial Success extension as described in the base specification using partialsuccess as the name of the extension.

Status code

The server SHOULD respond with a success status code 200 if the operation was considered partially successful, even if one or more items erorred.

An operation WILL be considered partially successful if there is value for the consumer that originated the request to use the response data in the originally intended manner.

# Response payload

Any unsuccessful entity in a partially successful response WILL NOT appear in the data object. Thus any errored entity will be ignored.

Any errors that happened during the generation of the response MAY be added in the payload as metadata for the consumer. To do so add an array of error objects, these objects MUST appear as described in the base JSON API specification, under the key errors inside of the meta object.

Semantics

The server MAY use any meta object at any level to convey more context to the source of the errors in the partially successful response. Thus, if violations happened while generating the fields inside of a resource object, the server MAY place the error objects in the meta belonging to the resource object.

If there is no other suitable placement, the server MAY use the meta object at the document root.

Examples

Example 1

GET /api/articles HTTP/1.1
Host: example.com
Content-Type: application/vnd.api+json; ext=partialsuccess
Accept: application/vnd.api+json; ext=partialsuccess

The example scenario is a GET request for a collection of articles. Given that one of the articles in the current page of results cannot be accessed by the authenticated user, then the server may respond with the following response (according to this specification).

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json; ext=partialsuccess

{
  "data": [
    {
      "type": "articles",
      "id": "7d4398f8-21fa-4ee8-8814-2c36d5627665",
      "attributes": {
        "title": "My custom title",
        "computedField": 42
      },
      "links": {
        "self": "http://example.com/api/articles/7d4398f8-21fa-4ee8-8814-2c36d5627665?_format=api_json"
      }
    }
  ],
  "meta": {
    "errors": [
      {
        "title": "Forbidden",
        "status": 403,
        "detail": "Access checks failed for entity node:2475.",
        "links": {
          "info": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4"
        },
        "code": 0
      }
    ]
  },
  "links": {
    "self": "http://example.com/api/articles"
  }
}

Example 2

GET /api/articles/7d4398f8-21fa-4ee8-8814-2c36d5627665 HTTP/1.1
Host: example.com
Content-Type: application/vnd.api+json; ext=partialsuccess
Accept: application/vnd.api+json; ext=partialsuccess

The example scenario is a GET request for single article. Given that one of the attributes of the article cannot be computed, then the server may respond with the following response (according to this specification).

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json; ext=partialsuccess

{
  "data": {
    "type": "articles",
    "id": "7d4398f8-21fa-4ee8-8814-2c36d5627665",
    "attributes": {
      "title": "My custom title"
    },
    "meta": {
      "errors": [
        {
          "title": "Internal Server Error",
          "status": 500,
          "detail": "Invalid value provided for field computedField.",
          "links": {
            "info": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1"
          },
          "code": 0
        }
      ]
    },
    "links": {
      "self": "http://example.com/api/articles/7d4398f8-21fa-4ee8-8814-2c36d5627665"
    }
  }
}
@elliotttf

This comment has been minimized.

Copy link

@elliotttf elliotttf commented Oct 6, 2016

RE errors, why not put them in the top level of the response as defined by the JSON API spec?

@e0ipso

This comment has been minimized.

Copy link
Owner Author

@e0ipso e0ipso commented Oct 6, 2016

RE errors, why not put them in the top level of the response as defined by the JSON API spec?

That was my first instinct, sadly that makes it invalid JSON API.

json api specification v1 1 still in development 2016-10-06 14-43-59

@elliotttf

This comment has been minimized.

Copy link

@elliotttf elliotttf commented Oct 6, 2016

Ah hah! 👍

@meShar

This comment has been minimized.

Copy link

@meShar meShar commented Nov 3, 2018

why cant we return 200 if everything succeeds and 207 if one or more fail? This allows the client to use 200 standards for complete successes and deviate only if we see failures

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment