Two Steps Retrieval¶
Important
Two Step Retrieval loads only a partial set of the related objects (default size of the retrieved related collection is 10). To load additional related objects, use the Relation Paging API .
With this approach a collection of related objects for a specific relation property in a parent object is retrieved from the server. The client application must know parent object's objectId
. The API loads a collection of related children for one property at a time. Child objects retrieved in paged sets, see the Relation Paging API sectionfor additional details.
GET https://xxxx.backendless.app/api/data/[TABLE-NAME]/[OBJECT-ID]/[relatedPropertyName]?
sortBy=[sortingPropertiesList]&props=[retrievalPropertiesList]
where:
Argument | Description |
---|---|
[TABLE-NAME] |
Name of the table where the data is to loaded from. |
[OBJECT-ID] |
ID of the object for which to load specified relations. |
[relatedPropertyName] |
Name of a related property to load. For example, if table Person has a relation column homeAddress pointing to an object in the Address table, the value would be homeAddress . |
[sortingPropertiesList] |
Optional argument. If provided, must contain one or more properties separated by comma. The specified properties will be used by the server to sort the resulting collection by. To request the descending sort order for a property, add the DESC keyword after the property name separated with space, for example sortBy=name DESC . When specifying multiple properties. the comma between the property names must be URL-encoded as %2C . |
[retrievalPropertiesList] |
Optional argument. If provided, must contain one or more properties from the related table which should be returned in every object included into the response. When specifying multiple properties. the comma between the property names must be URL-encoded as %2C . |
In addition to the GET request documented above, the same API is available with a POST operation where the sortingPropertiesList
and the retrievalPropertiesList
are in the request body as opposed to the request URL:
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/data/[TABLE-NAME]/[OBJECT-ID]/[relatedPropertyName]/load
Request Headers¶
user-token: value-of-the-user-token-header-from-login
Content-Type:application/json
where:
Argument | Description |
---|---|
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 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. |
Content-Type |
Must be set to application/json . This header is mandatory. |
Request Body¶
{
"sortBy":"sortingPropertiesList",
"props":"retrievalPropertiesList"
}
where:
Argument | Description |
---|---|
sortingPropertiesList |
Must contain one or more properties separated by comma. The specified properties will be used by the server to sort the resulting collection by. To request the descending sort order for a property, add the DESC keyword after the property name separated with space, for example sortBy=name DESC . |
retrievalPropertiesList |
Must contain one or more properties from the related table which should be returned in every object included into the response. |
Suppose the Person
table has a one-to-many relationship column friends
pointing to the Users
table. The code below retrieves related BackendlessUser
objects for a specific Person
object:
curl \
-X POST'xxxx.backendless.app/api/data/Person/parentObjectId/address/load'
\--header
'Content-Type: application/json'
\--data-raw '{
"sortBy":"name",
"props":"friends,name"
}'