AWS Security Blog

New Cloud Directory API Makes It Easier to Query Data Along Multiple Dimensions

Amazon Cloud Directory enables you to build flexible, cloud-native directories for organizing hierarchies of data along multiple dimensions. For example, you can create an organizational structure that you can navigate through multiple hierarchies for reporting structure, location, and cost center. With Cloud Directory, you can create directories for a variety of use cases, such as course catalogs and device registries.

Today, we made available a new Cloud Directory API, ListObjectParentPaths, that enables you to retrieve all available parent paths for any directory object across multiple hierarchies. Use this API when you want to fetch all parent objects for a specific child object. The order of the paths and objects returned is consistent across iterative calls to the API, unless objects are moved or deleted. In case an object has multiple parents, the API allows you to control the number of paths returned by using a paginated call pattern.

In this blog post, I use an example directory to demonstrate how this new API enables you to retrieve data across multiple dimensions to implement powerful applications quickly.

An example: Expense-approval application

Let’s look at an expense-approval use case. A typical corporate expense-approval application needs to understand the reporting dimension for an employee to route expense reports for approval. The application also needs to understand departmental budgets and individual expense limits based on a finance cost center dimension. If the expense-approval application were built using traditional solutions, you would have to run one query to get the organization’s reporting structure for the list of expense approvers and another query for the cost-center hierarchy to get budget data. However, with the new Cloud Directory API, you can query for all this information with a single call.

In the following diagram, the multidimensional hierarchy includes a reporting dimension and a finance dimension, with cost centers for groups and departments.

Diagram of a multidimensional hierarchy

Let’s say our expense-approval application needs to process an expense report for Tim. In order to complete the workflow, the application needs to understand the reporting structure of Tim as well as his department’s and his budget constraints.

The ListObjectParentPaths API enables the expense-approval application to get both the approval chain and the budget constraints in a single call. For example, when requesting parent paths for object Tim, the response gives both the reporting chain (John, Jane) and the cost center (Corporate, Cost Center 123) as parent paths.

Request: ListObjectParentPaths(“Tim”, PageToken: null, MaxResults = 2)

Response: [{/Reporting/Research/Data Scientist, [Directory Root, John, Jane, Tim]},{/Finance/R&D/a, [Directory Root, Corporate, Cost Center 123, Tim]}], PageToken: null

The preceding request and response show how a single Cloud Directory API call can fetch all relevant information in my application to process the expense report for employee, Tim. My application’s logic can check the expense report against the applicable budget constraints and approval chain to process it.

Note that in the previous request, I set MaxResults to 2, this enabled me to retrieve both paths with the objects in a list. However, if I set MaxResults to 1, I need to make two paginated calls with page tokens to get all paths with lists of objects.

Request: ListObjectParentPaths(“Tim”, PageToken: null, MaxResults = 1)

Response: {/Reporting/Research/Data Scientist, [Directory Root, John, Jane, Tim]}, PageToken: <encrypted_next_token>


Request: ListObjectParentPaths(“Tim”, PageToken: <encrypted_next_token> ,  MaxResults = 1)

Response: {/Finance/R&D/a, [Directory Root, Corporate, Cost Center 123, Tim]}, PageToken: null


With Cloud Directory, you can build multidimensional hierarchies to model complex relationships. Use the new API to easily collect and evaluate all the dimensions and associated information. For more information about the new API, see the Objects and Links documentation.

If you have comments about this blog post, submit them in the “Comments” section below. If you have questions about implementing the solution in this blog post, start a new thread in the Directory Service forum.

– Mahendra