Batch operation

ENDPOINT /api/object/batch (POST only)

Batch operations allow objects to be created, read, updated, and deleted.

POST an XML document to the endpoint with the Content-Type header set to text/xml; charset=utf-8. This has the format:

  • request
    • identifier – caller identifier. Must not be empty, but can be the same on every request
    • operations
      • create *
      • read *
        • ref – objref of object to read
      • delete *
        • ref – objref of object to delete
      • update *
        • ref – objref of object to update
        • object – object as Object XML representation. If the included_attrs attribute is present, only the listed attributes will be replaced in the object.
          • attributes
            • included_attrs ? – if present, then only the attributes listed are deleted, and then replaced with the attributes in this operation. Otherwise all attributes are deleted, and replaced with the ones in this operation.

The document must include the <?xml version="1.0" encoding="UTF-8"?> declaration.

A batch may contain up to 64 operations. A request containing more will be rejected by the server, with no operations performed.

Operations can be in any order, and are executed in that order.

Response is:

  • response
    • status – ‘success’ if the basic parsing and setup worked, individual operations can fail
    • identifier – identifier copied from the request
    • create *
      • index – index of operation in the request
      • url – full URL of the new object
      • ref – objref of new object
    • read *
      • index – index of operation in the request
      • url – full URL of the object
      • ref – objref of object
      • object – object, as Object XML representation
    • update *
      • index – index of operation in the request
      • url – full URL of the object
      • ref – objref of object
    • delete *
      • index – index of operation in the request
      • ref – objref of object
    • error *
      • index – index of operation in the request
      • code ? – internal code if available
      • message
        • TEXT – descriptive error message

Each operation in the request has a corresponding create, read, update, delete or error element, in the same order as the operations in the request.

NOTE: Check the account is sufficiently under the objects limit before creating large numbers of objects.

If the object limit is exceeded and the batch includes a create operation, the entire batch will be rejected with an error response. None of the operations will be executed.