Overview

The "Deep Save" functionality is a single API request that can create or update a complete "object tree" in the database using a single transaction. The object tree starts with the root object and includes other child objects, their corresponding children and so on. Consider the following object diagram:

There is a parent object of type Person, the object has a relation through the homeAddress property to an Address object. Using the Deep Save functionality, you can perform the following operations with a single API call:

• Save new Person and the related Address in the database. Both objects will be saved in the corresponding tables and a relationship at the database level will be created between them.
• Update existing Person in the database with a new related Address object. The new Address object will be stored in the corresponding table and the relationship will be created in the database.
• Update both Person and Address objects in the database.

Important

Since the Deep Save API uses Backendless transactions, the tables/schema where the data is being saved must be created before the API is used. This requirement stems from the Transaction API that requires the schema to be pre-created.

Method

PUT

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/data/<table-name>/deep-save 

where:

Argument	Description
<table-name>	name of the table where the root object needs to be saved.

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 user-token is set in the request, the currently logged in user will be assigned to the ownerId property of the objects which are being saved.  Additionally, 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

A JSON object with all necessary relations to save/update in the database.

Response Body

A JSON object with all relations from the request. If the object and/or related objects were new, Backendless assigns objectId values.

Codeless Reference

Consider the example below. The example stores a new Person and the related Address objects in the database using the Deep Save API:

curl \  
-H Content-Type:application/json \  
-X PUT  \  
-d "{  
  \"name\":\"Bob\",  \  
  \"age\":30,        \  
  \"homeAddress\": { \  
    \"city\":\"New York\", \  
    \"country\":\"USA\"    \  
  }  \  
}" \  
-v https://xxxx.backendless.app/api/data/Person/deep-save

Server response:

{
  "created": 1624089318000,
  "name": "Bob",
  "___class": "Person",
  "ownerId": null,
  "updated": null,
  "objectId": "8CD19C7B-5B94-4E25-8DF6-B72D7DC6DC80",
  "age": 30,
  "homeAddress": {
    "country": "USA",
    "city": "New York",
    "created": 1624089318000,
    "___class": "Address",
    "ownerId": null,
    "updated": null,
    "objectId": "F57C7B6C-1FC5-4789-B1AD-A945BF65F5F7"
  }
}

Codeless reference:

Once the code runs, you will find the following two objects in the database. Notice that a single deep-save API call resulted in both objects saved in the corresponding tables and a relationship in the homeAddress column in the Person table points to the Address object:

Person table:

Address table: