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

Endpoint URL

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

https://xxxx.backendless.app/api/transaction/unit-of-work

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.