The Hierarchy API

Release date: 6th November 2024

Hierarchies can be used to model anything from a page structure for a website to a structured list of product content. This release features a new Hierarchy API that makes hierarchies easier and more efficient for developers to work with.

The Hierarchy API is a new Content Delivery API that allows developers to do the following:

Get all the nodes at all levels of a hierarchy.
Easily retrieve descendants of a specified node in a part of a hierarchy. This could be a product category such as "Electricals" or "Homeware" in a page hierarchy, or a section of a site map.

Using the Hierarchy API
Link copied!

Given the ID of a hierarchy node, this API will return the descendants to the level specified.

Specify the hub name and the content item id of the parent node whose descendants will be returned. The optional hierarchyDepth parameter allows you to choose how many levels deep to traverse the hierarchy. If you don't specify hierarchyDepth then only the immediate descendants of the specified node will be returned (a depth of 1).

https://{hubname}.cdn.content.amplience.net/content/hierarchies/descendants/id/{id}

The API uses a pre-sort algorithm, starting with the first child node of a parent, retrieving all of its descendants, and then retrieving the descendants of each of its sibling nodes in turn.

You can also sort the content items in the API response using your own predefined sort key.

See the Hierarchy API page for more detail and examples.

Example
Link copied!

The image below shows a hierarchy created from our page hierarchy schema example. The parent node is "Ideas and advice", a content item with the id 4c67ca5a-6050-490a-9859-be20e81ac89d.

The ideas and advice hierarchy

The entire hierarchy has a depth of 3 levels. To retrieve all descendants of the 'Ideas and advice' node, we specify the following hierarchy API request, with a hierarchy depth of 3.

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. The response is returned in the default sort order, returning "Heating and plumbing", "Lighting and electrical" and all its descendants, "Outdoor and garden" and all its descendants and then "Painting and decorating". You can also use define your own sort key to sort the response.

Example response

{
  "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
  }
}