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.