In a previous post, we discussed the URL parameters supported by the API. In today's post, we'll focus on the Depth parameter.

The REST API can retrieve entities at three different levels of depth :

  1. minimal
  2. partial
  3. complete

 

In general, requests at minimal depth will perform best, as they scan the least amount of data. The descriptions below should help you choose the right level of depth for your request.

 

Minimal

Only a small number of the entity's properties are returned.

These are properties common to all records :

  • the entity name, type and id
  • the dates the entity was created, last updated and last accessed

Minimal depth typically results in the best performance, as the time needed to retrieve the information in minimized.

 

The following example shows a contact retrieved at minimal depth :

 

GET https://.../data/contacts?search=col&depth=minimal&count=5

 

{
    "elements": [
        {
            "type": "Contact",
            "id": "515",
            "createdAt": "1239744629",
            "depth": "minimal",
            ...
        },
        {
            "type": "Contact",
            "id": "516",
            "createdAt": "1239806222",
            "depth": "minimal",
            ...
        },
        ...
    ],
    "page": 1,
    "pageSize": 5,
    "total": 2566
}



 

Partial

All of the entity's properties are returned and if the entity is related to other objects, those entities are returned at minimal depth.

 

The following example shows a landing page retrieved at partial depth :

 

GET https://.../assets/landingPage/123?depth=partial

 

{
      "type": "LandingPage",
      "id": "123",
      "depth": "partial",
      "folderId": "456",
      "currentStatus": "Active",
      "accessedAt": "1262127601",
      "createdAt": "1250826031",
      "createdBy": "789",
      "updatedAt": "1260548979",
      "updatedBy": "123",
      "name": "My Landing Page",
      "docType": "...",
      "header": "...",
      "body": "...",
      "footer": "...",
      "layout": "...",
      ...
}



 

Complete

All of the entity's properties are returned and all related entities are returned at complete depth.

 

The following example shows a form retrieved at complete depth :

 

GET GET https://.../assets/form/1619?depth=complete

 

{
    "type": "Form",
    "currentStatus": "Draft",
    "id": "1619",
    "createdAt": "1277226536",
    "createdBy": "23",
    "depth": "complete",
    "folderId": "18071",
    "updatedAt": "1285010566",
    "updatedBy": "34",
    "elements": [
        {
            "type": "FormField",
            "id": "4538",
            "name": "First Name",
            "instructions": "",
            "createdFromContactFieldId": "100002",
            "dataType": "text",
            "displayType": "text",
            "fieldMergeId": "143",
            "htmlName": "firstName",
            "validations": []
        },
        {
            "type": "FormField",
            "id": "4539",
            "name": "Last Name",
            "instructions": "",
            "createdFromContactFieldId": "100004",
            "dataType": "text",
            "displayType": "text",
            "fieldMergeId": "3",
            "htmlName": "lastName",
            "validations": []
        },
        ...
    ],
    ...
}


 

We hope that you find this helpful.

 

Thanks,

Fred