Skip to content

Unit of Work API

The heart of the Backendless Transactions API is a request called UnitOfWork. It used by the client applications to compose a transaction. Composing a transaction means adding various database operations to a unit of work. These operations may be "linked" between each other by using the output/result on one operation as the input for another.

When the server receives a UnitOfWork request, it starts processing its operations. The server executes all operations one-by-one in the context of a single database transaction. If any of the operations fails, Backendless rolls back all the changes and returns the information about the result of each operation to the client. However, if all operations succeeded, the entire database transaction is committed. This means the data will be finalized in the database.

Running a Transaction

Use the API below to run a transaction in Backendless:

Method

POST

URL

https://api.backendless.com/<application-id>/<REST-api-key>/transaction/unit-of-work

where:

Argument                Description
<application-id> the ID of your application You can obtain the value in the Manage > App Settings section of the Backendless Console.
<REST-api-key> REST API key of your application. You can obtain the value in the Manage > App Settings section of the Backendless Console.

Request Headers

Content-Type:application/json  
user-token: value-of-the-user-token-header-from-login

where:

Argument                Description
Content-Type Must be set to application/json. This header is mandatory.
user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If the header is present, the operation will be executed with the security policy associated with the currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request Body

{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [
    {
      "operationType": "CREATE" |  "CREATE_BULK" | "UPDATE" | "UPDATE_BULK" | "DELETE" | "DELETE_BULK" | "FIND" | "ADD_RELATION" | "SET_RELATION" | "DELETE_RELATION",
      "table": "TABLENAME",
      "opResultId": "OPRESULT-ID",
      "payload": {
          PAYLOAD VARIES BETWEEN OPERATIONS
      }
    },
    {

    },
    {

    }
  ]
}

where:

Argument                Description
isolationLevelEnum A property containing a value which sets the isolation level for this transaction. Supported values are: "REPEATABLE_READ","READ_COMMITTED", "READ_UNCOMMITED", "SERIALZABLE". For more information about transaction isolation levels, see the Isolation Level section.
operationType A property containing a string value indicating the type of the operation object. Supported values are:
"CREATE"  - saving a single object operation
"CREATE_BULK"  - saving multiple objects operation
"UPDATE" - updating a single object operation
"UPDATE_BULK" - updating multiple objects operation
"DELETE" - deleting a single object operation
"DELETE_BULK" - deleting multiple objects operation
"FIND" - retrieving objects operation
"ADD_RELATION" - an operation for adding child objects to a parent for a relation
"SET_RELATION" - an operation for setting child objects to a parent for a relation
"DELETE_RELATION" - an operation for disconnecting child objects from the parent for a relation
table A string property which must contain the name of the table where the operation will be performing its work. For example, if it is an operation to store an object in a table called Person, then the value of the table property must be "Person".
opResultId An optional property. If present must contain a unique string value identifying the operation. For more information see the OpResult Id section below.
payload A JSON object with the details specific to each operation. See the sections describing supported operations for details about the payload format.

Return Value

A JSON object of the following format:

{
  "success": true | false,
  "error": null | string-value,
  "results": {
    "operationResultId1": {
      "type": "OPERATION-TYPE",
      "result": VALID-JSON,
    "operationResultId2": {
      "type": "OPERATION-TYPE",
      "result": VALID-JSON
    }
  }
}

where:

Argument                Description
success Is a property indicating whether the entire transaction has completed successfully or failed and thus had been rolled back.
error If the transaction resulted in an error, this property contains the error message.
operationResultId1..N Reference to a transaction operation. The name of the property is the same as the value as in the opResultId property from the corresponding operation in the request.
type Type of the operation, it contains the same value as the operationType property in the corresponding operation in the request.
result A JSON value which is the result of the specific operation identified by the operationResultId1..N property.

Operations

UnitOfWork supports the following database operations. Each operation is described in detail in the sections of this guide that follow.

OpResult Id

Every operation in a transaction can be identified with a property called opResultId. It is a free form, string value which you can assign to an operation for the following purposes:

  1. An operation with the opResultId property can be referred to from another operation. This is done to indicate that the results of one operation should be used as the input argument in another one.
  2. When the transaction is complete, you can see the results of each operation. These results are mapped to the value of the opResultId property.

The opResultId property is not required, when it is not present in an operation object, server generates and assigns a value using the following pattern:

operation name + table where operation is performed + sequential number

For additional details about OpResult ID, see the Operation Result chapter of this guide.