index.md

layout	title
page	Bulk Extension

Status

Extensions are an experimental feature and should be considered a work in progress. There is no official support for extensions in the base JSON API specification.

Introduction

The "Bulk extension" is an official extension of the JSON API specification. It provides support for performing multiple operations in a request, including adding and removing multiple resources.

Servers and clients MUST negotiate support for and use of the Bulk extension as described in the base specification using bulk as the name of the extension.

Bulk Operations

As mentioned in the base specification, a request MUST completely succeed or fail (in a single "transaction").

Therefore, any request that involves multiple operations MUST only succeed if all operations are performed successfully. The state of the server MUST NOT be changed by a request if any individual operation fails.

Creating Multiple Resources

Multiple resources can be created by sending a POST request to a URL that represents a collection of resources. The request MUST include an array of resource objects as primary data. Each resource object MUST contain at least a type member.

For instance, multiple photos might be created with the following request:

POST /photos HTTP/1.1
Content-Type: application/vnd.api+json; ext=bulk
Accept: application/vnd.api+json; ext=bulk

{
  "data": [{
    "type": "photos",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    }
  }, {
    "type": "photos",
    "attributes": {
      "title": "Mustaches on a Stick",
      "src": "http://example.com/images/mustaches.png"
    }
  }]
}

Updating Multiple Resources

Multiple resources can be updated by sending a PATCH request to a URL that represents a collection of resources to which they all belong. The request MUST include an array of resource objects as primary data. Each resource object MUST contain at least type and id members.

For example:

PATCH /articles HTTP/1.1
Content-Type: application/vnd.api+json; ext=bulk
Accept: application/vnd.api+json; ext=bulk

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "To TDD or Not"
    }
  }, {
    "type": "articles",
    "id": "2",
    "attributes": {
      "title": "LOL Engineering"
    }
  }]
}

Deleting Multiple Resources

Multiple resources can be deleted by sending a DELETE request to a URL that represents a collection of resources to which they all belong.

The body of the request MUST contain a data member whose value is an an array of resource identifier objects.

For example:

DELETE /articles HTTP/1.1
Content-Type: application/vnd.api+json; ext=bulk
Accept: application/vnd.api+json; ext=bulk

{
  "data": [
    { "type": "articles", "id": "1" },
    { "type": "articles", "id": "2" }
  ]
}