Retrieving hierarchical content

On this page we provide an overview of how to retrieve content items from a hierarchy. You can find more information and examples on the Hierarchy API and Filter API pages.

When to use the Hierarchy API and Filter API

Both the Hierarchy API and Filter API have their advantages:

• The Filter API can be used to retrieve only the immediate children of a hierarchy node. However, you can filter by the parent node and the value of a property.

• The Hierarchy API can be used to retrieve all nodes in a hierarchy, or parts of a hierarchy, up to a maximum depth of 14 levels.

• The Filter API can be used to retrieve linked content, the Hierarchy API does not currently return linked content.

• Hierarchy API requests have a larger page size, 100 items compared to a maximum of 50 for the Filter API.

The Hierarchy API is better suited to use cases where large hierarchies are being returned with minimal linked content, while the Filter API is better suited to use cases with a lot of linked content.

Using hierarchies with the Content Delivery API

When you publish a hierarchy node you can choose whether to publish it on its own or together with its dependents. The Content Delivery API includes some additional information about a node under the hierarchy element. Here's an example of the content returned for the root of the hierarchy- that is the node that has no parent item. You can see that root is set to true.

{
  "content": {
    "_meta": {
      "name": "Website menu",
      "schema": "https://example.com/site-menu-item",
      "hierarchy": {
        "root": true
      },
      "deliveryId": "b158fe6b-fe4b-46e3-92c5-33f8a4e5675c"
    },
    "title": "Website menu",
    "description": "Menu for our website"
  }
}

Here's the content returned for an item named "Clearance", you will notice that this includes a parentId element. This is the node's immediate parent, in this case the root node shown above. You can use the parentId to traverse back up the tree or with the Filter API to find the immediate children of the parent.

Use the Hierarchy API to find all descendants of the specified node, which can be the entire hierarchy or just a part of it.

{
  "content": {
    "_meta": {
      "name": "Clearance",
      "schema": "https://example.com/site-menu-item",
      "hierarchy": {
        "parentId": "b158fe6b-fe4b-46e3-92c5-33f8a4e5675c",
        "root": false
      },
      "deliveryId": "da2cc1b1-d7f5-4743-b7c0-a3c893363c3e"
    },
    "title": "Clearance",
    "description": "Items that must go"
  }
}

Retrieving all descendants of a hierarchy node

The Hierarchy API allows you to retrieve all descendants of a specified node in a hierarchy. The following example shows how to retrieve all descendants of the node with the content item id 4c67ca5a-6050-490a-9859-be20e81ac89d to a depth of 3 levels.

https://docsportal.cdn.content.amplience.net/content/hierarchies/descendants/id/4c67ca5a-6050-490a-9859-be20e81ac89d?hierarchyDepth=3

You can see the response to this request by expanding the section below.

Example response from the Hierarchy API

{
  "responses": [
    {
      "content": {
        "_meta": {
          "name": "Heating and plumbing",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "ideas-and-advice/heating-and-plumbing",
          "hierarchy": {
            "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d",
            "root": false
          },
          "deliveryId": "2e924e92-5c68-485f-aaa4-54d3c630227e"
        },
        "title": "Heating and plumbing",
        "description": "All your plumbing questions answered",
        "ranking": 1
      }
    },
    {
      "content": {
        "_meta": {
          "name": "Lighting and electrical",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "ideas-and-advice/lighting-and-electrical",
          "hierarchy": {
            "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d",
            "root": false
          },
          "deliveryId": "2dd210c1-0418-442d-8b50-bb089de773f9"
        },
        "title": "Lighting and electrical",
        "description": "Your questions answered on all things lights and electrics",
        "ranking": 2
      }
    },
    {
      "content": {
        "_meta": {
          "name": "How to change a socket",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "lighting-and-electrical/how-to-change-a-socket",
          "hierarchy": {
            "parentId": "2dd210c1-0418-442d-8b50-bb089de773f9",
            "root": false
          },
          "deliveryId": "bff3769a-b8f0-4eb0-b399-b7df6cf92417"
        },
        "title": "How to change a socket",
        "description": "How to safely change an electrical socket",
        "ranking": 1
      }
    },
    {
      "content": {
        "_meta": {
          "name": "How to run a new cable",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "lighting-and-electrical/how-to-run-a-new-cable",
          "hierarchy": {
            "parentId": "2dd210c1-0418-442d-8b50-bb089de773f9",
            "root": false
          },
          "deliveryId": "09d8ac5b-c24c-4d2e-936e-ae4751543b2e"
        },
        "title": "How to run a new cable",
        "description": "Adding a new cable, the easy and safe way",
        "ranking": 2
      }
    },
    {
      "content": {
        "_meta": {
          "name": "Outdoor and garden",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "ideas-and-advice/outdoor-and-garden",
          "hierarchy": {
            "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d",
            "root": false
          },
          "deliveryId": "d09cea6f-265d-4e9d-98d9-4c5e95f7afa9"
        },
        "title": "Outdoor and garden",
        "description": "Hints and tips for keeping your garden looking great",
        "ranking": 3
      }
    },
    {
      "content": {
        "_meta": {
          "name": "Gardening questions answered",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "outdoor-and-garden/gardening-questions-answered",
          "hierarchy": {
            "parentId": "d09cea6f-265d-4e9d-98d9-4c5e95f7afa9",
            "root": false
          },
          "deliveryId": "ce110f22-d85d-4bf1-9f20-5a6b5795ecd6"
        },
        "title": "Gardening questions answered",
        "description": "Everything you need to know about planting and care of your garden",
        "ranking": 1
      }
    },
    {
      "content": {
        "_meta": {
          "name": "How to sow new grass seeds",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "outdoor-and-garden/gardening-questions-answered/how-to-sow-new-grass-seeds",
          "hierarchy": {
            "parentId": "ce110f22-d85d-4bf1-9f20-5a6b5795ecd6",
            "root": false
          },
          "deliveryId": "5992d135-cd7b-4c57-ba2c-bf1103150c58"
        },
        "title": "How to sow new grass seeds",
        "description": "A new lawn made easy",
        "ranking": 1
      }
    },
    {
      "content": {
        "_meta": {
          "name": "Painting and decorating",
          "schema": "https://schema-examples.com/page-hierarchy-node",
          "deliveryKey": "ideas-and-advice/painting-and-decorating",
          "hierarchy": {
            "parentId": "4c67ca5a-6050-490a-9859-be20e81ac89d",
            "root": false
          },
          "deliveryId": "31c0b684-7a28-47ad-a871-f1882ec408fa"
        },
        "title": "Painting and decorating",
        "description": "How to keep your home looking good as new",
        "ranking": 4
      }
    }
  ],
  "page": {
    "responseCount": 8
  }
}

Listing immediate children of a hierarchy node

Using the Filter API you can list all the children of a specified parent node by setting the filter path to /_meta/hierarchy/parentId,as shown in the content returned from the Delivery API, and setting the parent id to the deliveryId of the item whose children you want to return. You can use the Hierarchy API to return all children in all levels of a hierarchy.

In the example filter API request shown below we are requesting all the children of the hierarchy node with the id "b158fe6b-fe4b-46e3-92c5-33f8a4e5675c". Note that just the immediate children will be returned.

{
  "filterBy": [
    {
      "path": "/_meta/hierarchy/parentId",
      "value": "b158fe6b-fe4b-46e3-92c5-33f8a4e5675c"
    }
  ]
}

Try it out

To try out the filter request use the following cURL.

curl -d '{
   "filterBy":[
      {
         "path":"/_meta/hierarchy/parentId",
         "value":"b158fe6b-fe4b-46e3-92c5-33f8a4e5675c"
      }   ]
}' -H "Content-Type: application/json" -X POST 'https://ampproduct-doc.cdn.content.amplience.net/content/filter'

An example response is shown below. These are the items that have the node with the id "b158fe6b-fe4b-46e3-92c5-33f8a4e5675c" as their parent.

{
  "responses": [
    {
      "content": {
        "_meta": {
          "name": "Homewares",
          "schema": "https://example.com/site-menu-item",
          "hierarchy": {
            "parentId": "b158fe6b-fe4b-46e3-92c5-33f8a4e5675c",
            "root": false
          },
          "deliveryId": "44ca42f3-8953-4ff5-99a8-ac48980e63d2"
        },
        "title": "Homewares",
        "description": "For the home"
      }
    },
    {
      "content": {
        "_meta": {
          "name": "Clearance",
          "schema": "https://example.com/site-menu-item",
          "hierarchy": {
            "parentId": "b158fe6b-fe4b-46e3-92c5-33f8a4e5675c",
            "root": false
          },
          "deliveryId": "da2cc1b1-d7f5-4743-b7c0-a3c893363c3e"
        },
        "title": "Clearance",
        "description": "Items that must go"
      }
    }
  ],
  "page": {
    "responseCount": 2
  }
}

Related pages

Introducing hierarchies

Creating content type schemas for hierarchies

Working with hierarchies

List, filter and sort content

Hierarchy API

Hierarchies limits