Composite requests

The REST API provides advanced capabilities for processing multiple operations through a single HTTP call using the composite request service.

Use the composite request service to send a request containing multiple sub-requests for different objects or services in a single HTTPS call. For example, you can create a new contact, update an existing vendor, query bills, and so forth, in a single request.

The composite request service is designed to:

• Support mixed operations, for example GET and POST.
• Support a combination of operations and services in one request. Each sub-request path is restricted to /objects/... or /services/....
• Support operations on different objects in one request.
• Use the output from one sub-request in subsequent sub-requests. For example, you can save the key of the newly created object and use it in subsequent sub-requests.
• Support HTTP request and response headers for each sub-request. Authorization, Content-Type and Accept headers cannot be specified for each sub-request, they are inherited from the top level.

The composite service supports between 2 and 10 sub-requests. Permissions are checked for each sub-request during execution.

All sub-requests must use the same version of the API as the composite request. You cannot use a combination of API versions.

Sub-requests are executed sequentially. The execution stops on first failure with no rollback of any previous sub-requests.

Composite request responses are synchronous.

Composite request URI and examples

See the Send a composite request reference page for a list and description of fields you can include in a composite request. Send the request to the following endpoint URL using the POST method:

  https://{hostname}/api/{version}/services/core/composite

Sample request body

[
    {
      "method": "POST",
      "path": "/objects/accounts-payable/vendor",
      "body": { ... },
      "resultReference": "vendor",
      "headers": {
        "X-ABC": "123"
      }
    },
    {
      "method": "GET",
      "path": "/objects/accounts-payable/vendor/@{vendor[1].key}"
    }
]
```/

Sample response body - success

```yaml
{
    "ia::result": [
      {
        "ia::result": [{ ... }],
        "ia::meta": {
          "totalCount": 1
        },
        "ia::status": 200,
        "ia::headers": {
          "X-ORM-ACTION": "create"
        }
      },
      {
        "ia::result": [{ ... }],
        "ia::meta": {
          "totalCount": 1
        },
        "ia::status": 200
      }
    ],
    "ia::meta": {
      "totalCount": 2,
      "totalSuccess": 2,
      "totalError": 0
    }
}

Sample response body - failure

{
    "ia::result": [
      {
        "ia::error": [{ ... }],
        "ia::meta": {
          "totalCount": 1
        },
        "ia::status": 400
      },
      {
        "ia::error": [{ <message that the request was not processed> }],
        "ia::meta": {
          "totalCount": 1
        },
        "ia::status": 422
      }
    ],
    "ia::meta": {
      "totalCount": 2,
      "totalSuccess": 0,
      "totalError": 2
    }
}