e0ipso/JSON API Partial Success.md

## JSON API Partial Success.md

      
    Raw
  

              JSON API Partial Success.md
            
          
    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"
    }
  }
}