Skip to content

Related Objects

Establishing object relationship

The process of establishing a relationship between multiple objects in Backendless 3.x is by saving the parent object which references its child(ren) in the same object hierarchy/tree. Version 5 changes the mechanism by introducing a dedicated operation which establishes a relationship between the objects. The example below stores two objects in Backendless Data service: Contact and Address and then sets up a relationship between them:

Version 3.x

Save Contact object:

curl \  
-H application-id:application-id-value-from-console \  
-H secret-key:secret-key-value-from-console  \  
-H Content-Type:application/json  \  
-X POST  \  
-d "{\"name\": \"Joe\", \"age\": 27, \"phone\": \"1-972-5551212\", \"title\": \"Plumber\" }" \  
-v https://api.backendless.com/v1/data/Contact 

Server response:

{  
  "phone": "1-972-5551212",  
  "created": 1485820899000,  
  "___class": "Contact",  
  "name": "Joe",  
  "title": "Plumber",  
  "ownerId": null,  
  "updated": null,  
  "age": 27,  
  "objectId": "660B5250-BBCF-1A37-FF9E-7887C67ABD00",  
  "__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":[  
             \"phone\",\"created\",\"___saved\",\"___class\",\"name\",  
             \"title\",\"ownerId\",\"updated\",\"age\",\"objectId\"],  
             \"relatedObjects\":{}}"  
}

Save Address object:

curl \  
-H application-id:application-id-value-from-console \  
-H secret-key:secret-key-value-from-console  \  
-H Content-Type:application/json  \  
-X POST  \  
-d "{\"street\": \"123 Main St.\", \"city\": \"Denver\", \"state\": \"Colorado\"}" \  
-v https://api.backendless.com/v1/data/Address

Server response:

{  
  "city": "Denver",  
  "street": "123 Main St.",  
  "created": 1485821090000,  
  "___class": "Address",  
  "state": "Colorado",  
  "ownerId": null,  
  "updated": null,  
  "objectId": "FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00",  
  "__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":[  
              \"city\",\"street\",\"created\",\"___saved\",  
              \"___class\",\"state\",\"ownerId\",\"updated\",  
              \"objectId\"],\"relatedObjects\":{}}"  
}

Establish relationship between the two objects:

It is important to note that the request URL includes parent's objectId (Contact). The request body references the child object (Address) by its objectId and the table where it is stored:

curl \  
-H application-id:application-id-value-from-console \  
-H secret-key:secret-key-value-from-console  \  
-H Content-Type:application/json  \  
-X PUT  \  
-d "{\"addresses\":[{\"objectId\":\"FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00\", \"___class\":\"Address\"}]}" \  
-v https://api.backendless.com/v1/data/Contact/660B5250-BBCF-1A37-FF9E-7887C67ABD00

Server response:

{  
  "addresses": [  
    {  
      "___class": "Address",  
      "objectId": "FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00",  
      "updated": 1485821315000,  
      "city": "Denver",  
      "created": 1485821090000,  
      "street": "123 Main St.",  
      "state": "Colorado",  
      "ownerId": null,  
      "__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":[  
                  \"___class\",\"objectId\",\"updated\",\"city\",  
                  \"created\",\"street\",\"state\",\"ownerId\"],  
                  \"relatedObjects\":{}}"  
    }  
  ],  
  "created": 1485820899000,  
  "title": "Plumber",  
  "ownerId": null,  
  "__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":[  
              \"addresses\",\"phone\",\"created\",\"___savedRelations\",  
              \"___class\",\"__relatedschemaaddress\",\"name\",\"title\",  
              \"ownerId\",\"updated\",\"objectId\",\"age\"],  
              \"relatedObjects\":{\"addresses\":[\"FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00\"]}}",  
  "phone": "1-972-5551212",  
  "___class": "Contact",  
  "name": "Joe",  
  "updated": 1485821315000,  
  "objectId": "660B5250-BBCF-1A37-FF9E-7887C67ABD00",  
  "age": 27  
}

Version 5.x

Save Contact object:

curl \  
-H Content-Type:application/json  \  
-X POST  \  
-d "{\"name\": \"Joe\", \"age\": 27, \"phone\": \"1-972-5551212\", \"title\": \"Plumber\" }" \  
-v https://api.backendless.com/application-id/rest-api-key/data/Contact 

Server response:

{  
  "phone": "1-972-5551212",  
  "created": 1485820899000,  
  "___class": "Contact",  
  "name": "Joe",  
  "title": "Plumber",  
  "ownerId": null,  
  "updated": null,  
  "age": 27,  
  "objectId": "660B5250-BBCF-1A37-FF9E-7887C67ABD00",  
  "__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":[  
             \"phone\",\"created\",\"___saved\",\"___class\",\"name\",  
             \"title\",\"ownerId\",\"updated\",\"age\",\"objectId\"],  
             \"relatedObjects\":{}}"  
}

Save Address object:

curl \  
-H Content-Type:application/json  \  
-X POST  \  
-d "{\"street\": \"123 Main St.\", \"city\": \"Denver\", \"state\": \"Colorado\"}" \  
-v https://api.backendless.com/application-id/rest-api-key/data/Address

Server response:

{  
  "city": "Denver",  
  "street": "123 Main St.",  
  "created": 1485821090000,  
  "___class": "Address",  
  "state": "Colorado",  
  "ownerId": null,  
  "updated": null,  
  "objectId": "FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00",  
  "__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":[  
              \"city\",\"street\",\"created\",\"___saved\",  
              \"___class\",\"state\",\"ownerId\",\"updated\",  
              \"objectId\"],\"relatedObjects\":{}}"  
}

Establish relationship between the two objects:

It is important to note that the request URL includes parent's objectId (Contact) and the relation column name which also identifies the name of the table (addresses:Address:n). The request body references the child object (Address) by its objectId and the table where it is stored:

curl \  
-H Content-Type:application/json  \  
-X POST  \  
-d "[ \"FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00\" ]" \  
-v https://api.backendless.com/application-id/rest-api-key/data/Contact/660B5250-BBCF-1A37-FF9E-7887C67ABD00/addresses:Address:n

Server response is the number of objects set in the relation:

1

Deleting/breaking object relationship

Similar to establishing a relationship between objects, Backendless 3.x relied on the update operation which sends the parent object to the server with an updated list of child objects. Any children removed from the collection on the client-side, are removed on the server as a result of the update call. Version 5 introduces a dedicated method to remove a relationship between objects. The example below removes a relationship between a Contact object and the first related Address object:

Version 3.x

Retrieve Contact object with the related Address objects. The request fetches Contact object with objectId 660B5250-BBCF-1A37-FF9E-7887C67ABD00.

curl -X GET \  
-H application-id:application-id-value-from-console \  
-H secret-key:secret-key-value-from-console \  
http://api.backendless.com/v1/data/Contact/660B5250-BBCF-1A37-FF9E-7887C67ABD00?loadRelations=addresses

Server response:

{  
  "addresses": [  
    {  
      "city": "Denver",  
      "created": 1485821090000,  
      "street": "123 Main St.",  
      "___class": "Address",  
      "state": "Colorado",  
      "ownerId": null,  
      "updated": 1485821315000,  
      "objectId": "FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00"  
    }  
  ],  
  "phone": "1-972-5551212",  
  "created": 1485820899000,  
  "name": "Joe",  
  "___class": "Contact",  
  "title": "Plumber",  
  "ownerId": null,  
  "updated": 1485821315000,  
  "objectId": "660B5250-BBCF-1A37-FF9E-7887C67ABD00",  
  "age": 27,  
  "__updated__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":  
                      [\"addresses\",\"phone\",\"created\",\"name\",  
                       \"___class\",\"title\",\"ownerId\",\"updated\",  
                       \"objectId\",\"age\",\"__meta\"],  
                      \"relatedObjects\":{   
                      \"addresses\":[\"FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00\"]}}",  
  "__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":  
             [\"__updated__meta\",\"addresses\",\"phone\",\"created\",  
              \"name\",\"___class\",\"title\",\"ownerId\",  
              \"updated\",\"objectId\",\"age\"],  
             \"relatedObjects\":{\"addresses\":[\"FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00\"]}}"  
}

Send updated Contact to the server. The updated contact object must have the same __meta property, but modified "addresses" array:

curl -X PUT \  
-H "application-id: 31CB9FED-F34C-5541-FF26-6C2B6719F200" \  
-H "secret-key: CDB792A6-99FF-6AB4-FFE7-6D0BCB22AA00" \  
-H "Content-Type: application/json" \  
-d '{"addresses":[],"phone":"1-972-5551212","created":1485820899000, \  
     "name":"Joe","___class":"Contact","title":"Plumber", \  
     "ownerId":null,"updated":1485821315000,"objectId":"660B5250-BBCF-1A37-FF9E-7887C67ABD00", \  
     "age":27.0,"__meta":"{\"relationRemovalIds\":{},\"selectedProperties\": \  
     [\"__updated__meta\",\"addresses\",\"phone\",\"created\",\"name\", \  
      \"___class\",\"title\",\"ownerId\",\"updated\",\"objectId\",\"age\"], \  
     \"relatedObjects\":{\"addresses\":[\"FAF7E515-3A04-91B9-FF17-CA8BEEC0EB00\"]}}"}' \  
http://api.backendless.com/v1/data/Contact/660B5250-BBCF-1A37-FF9E-7887C67ABD00

Server response:

{  
  "addresses": [],  
  "phone": "1-972-5551212",  
  "created": 1485820899000,  
  "___class": "Contact",  
  "name": "Joe",  
  "ownerId": null,  
  "title": "Plumber",  
  "updated": 1485985183000,  
  "objectId": "660B5250-BBCF-1A37-FF9E-7887C67ABD00",  
  "age": 27,  
  "__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":[\"addresses\",\"phone\",\"created\",\"___class\",\"name\",\"ownerId\",\"title\",\"updated\",\"objectId\",\"age\",\"__meta\"],\"relatedObjects\":{}}"  
}

Version 5.x

Retrieve Contact object with the related Address objects. The request fetches Contact object with objectId 50E31E37-7E1B-99F5-FF65-DFC01AD11A00.

curl -X GET \  
http://api.backendless.com/application-id/rest-api-key/data/Contact/50E31E37-7E1B-99F5-FF65-DFC01AD11A00?loadRelations=addresses

Server response:

{  
  "addresses": [  
    {  
      "city": "Denver",  
      "street": "123 Main St.",  
      "created": 1485987106000,  
      "___class": "Address",  
      "state": "Colorado",  
      "ownerId": null,  
      "updated": null,  
      "objectId": "9017A169-DC95-422F-FFDB-D659327F7D00"  
    }  
  ],  
  "phone": "1-972-5551212",  
  "created": 1485987070000,  
  "name": "Joe",  
  "___class": "Contact",  
  "title": "Plumber",  
  "ownerId": null,  
  "updated": null,  
  "objectId": "50E31E37-7E1B-99F5-FF65-DFC01AD11A00",  
  "age": 27,  
  "__meta": "{\"relationRemovalIds\":{},\"selectedProperties\":[  
              \"__updated__meta\",\"addresses\",\"phone\",\"created\",  
              \"name\",\"___class\",\"title\",\"ownerId\",\"updated\",  
              \"objectId\",\"age\"],\"relatedObjects\":{\"addresses\":[  
              \"9017A169-DC95-422F-FFDB-D659327F7D00\"]}}"  
}

Break the relation between Contact and Address:

curl -X DELETE \  
-H "Content-Type: application/json" \  
-d '[ \"9017A169-DC95-422F-FFDB-D659327F7D00\" ]' \  
http://api.backendless.com/application-id/rest-api-key/data/Contact/50E31E37-7E1B-99F5-FF65-DFC01AD11A00/addresses

Server response:

1

Additional resources: