JSON API sub-request write operations

jsonapi-subrequest-write.md

JSON API sub-request write operations

This extension allows you to alter or create the contents of the relationships of a resource with a single operation. In order to control how the relationships, and their relationships in turn, are affected by the request this extension reserves the keyword subrequest inside of the meta of any relationship. The contents of the subrequest property MUST be a request object.

The request object MUST NOT be present if the relationship item is not being altered or created via POST, PUT or PATCH.

The actual payload for the sub-request will be found in the included section for compound documents.

Creating new elements for a relationship

If you are creating a new element for a relationship, you don't have a resource identifier available to identify the payload for the POST sub-request inside of the included section.

To overcome this, the consumer SHOULD provide a unique identifier that does not collide with any existing item in the resource. This ID SHOULD solely be used for the server to retrieve the body for the sub-request from the included section. The server SHOULD NOT use the provided identifier to create the new entity with that given id.

The consumers MAY use a consumer specific prefix to ensure that the generated ID does not clash with any existing one.

The request object

The request object MUST contain a method key containing the HTTP method, in capital letters, that will be used for the sub-request. The value for this property SHOULD be one of: POST, PUT or PATCH.

Additional, optional, properties for the request object are:

• headers: An object containing a list of header names and values. If empty, the sub-request SHOULD inherit the headers from the parent request.
• cookies: An object containing a list of cookie names and values. If empty, the sub-request SHOULD inherit the cookies from the parent request.

Example

The following PUT request will perform several actions in a single request:

1. Update the title of the article to be To TDD or Not.
2. Update the contents of tag 6 to replace it with the provided content.
3. Create a new tag and assign it to the updated article.

PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "To TDD or Not"
    },
    "relationships": {
      "tags": {
        "data": [
          {
            "type": "tags",
            "id": 6,
            "meta": {
              "subrequest": {
                "method": "PUT"
              }
            }
          },
          {
            "type": "tags",
            "id": "newTag_1",
            "meta": {
              "subrequest": {
                "method": "POST",
                "headers": {"Authorization": "Basic Yoasdkk1="}
              }
            }
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "tags",
      "id": "6",
      "attributes": {
        "name": "Batman!",
        "description": "The gadget owner."
      }
    },
    {
      "type": "tags",
      "id": "newTag_1",
      "attributes": {
        "description": "I can only say: 42."
      }
    }
  ]
}

Note that the specification of this extension purposely allows having relationships with sub-requests in the compound documents. In that spirit the tags 6 included item could have had a relationship with a sub-request.

Extension name

e0ipso/write-subrequests

See the extension spec for more information about extensions.