From organizational charts and product catalogs to nested comments and file systems, hierarchical data is everywhere. Modeling these tree-like relationships can be surprisingly complex, often leading to complicated database queries and brittle application logic. What if you could offload that complexity and manage hierarchies with a clean, intuitive API?
Enter tree.service.do, a service dedicated to making hierarchical data management simple. Our API lets you create, manage, and query complex tree structures effortlessly, so you can focus on building powerful applications, not wrestling with nested data.
This guide will walk you through your first five essential API calls to get you up and running in minutes. We'll build a simple company org chart to demonstrate just how easy it is.
To follow along, you'll need an API key from your tree.service.do dashboard. Once you have it, you can install our client SDK.
npm install @do-sdk/tree
Now, let's initialize the client and start building.
import { TreeClient } from '@do-sdk/tree';
// Initialize the client with your API key
const treeService = new TreeClient({ apiKey: 'YOUR_API_KEY_HERE' });
Everything starts with a tree. Think of this as the top-level container for your entire hierarchical structure. You might have one tree for your company's org chart and another for your website's navigation menu.
Creating a new tree is a single API call.
// 1. Create a new tree
const orgChart = await treeService.create({
name: 'Company Org Chart'
});
console.log(`Tree created with ID: ${orgChart.id}`);
This orgChart object is now your primary point of interaction for adding and managing nodes within this specific tree.
A tree needs a root—the single node at the very top of the hierarchy. In our org chart, this will be the CEO.
To add a node, we use the addNode method. We specify the path as / to indicate this is the root node. Each node can also hold a flexible data object, where you can store any custom metadata you need.
// 2. Add a root node for the CEO
const ceo = await orgChart.addNode({
path: '/', // The '/' path signifies the root
data: { title: 'CEO', name: 'Alice' }
});
console.log(`Added CEO ${ceo.data.name} with ID: ${ceo.id}`);
As our FAQ notes, this data field accepts any valid JSON, making it perfect for storing titles, SKUs, user IDs, or any other properties relevant to your application.
This is where the magic happens. To create a relationship, you simply define the new node's path relative to its parent. Let's add a CTO who reports to the CEO. The path will be /{parent_id}.
// 3. Add a child node for the CTO reporting to the CEO
const cto = await orgChart.addNode({
path: `/${ceo.id}`, // Path indicates parent is the CEO
data: { title: 'CTO', name: 'Bob' }
});
console.log(`Added CTO ${cto.data.name} reporting to ${ceo.data.name}`);
That's it! You've just modeled a hierarchical relationship without writing a single complex SQL join or managing adjacency lists. You can continue this pattern to build out the entire tree, adding engineers who report to the CTO, for example: path: /${ceo.id}/${cto.id}.
Once you have data in your tree, you'll need to retrieve it. You can fetch any node directly if you know its ID. This is useful for looking up a specific user, product category, or file.
// 4. Retrieve a specific node by its ID
const retrievedNode = await orgChart.getNode(cto.id);
console.log(`Retrieved Node: ${retrievedNode.data.title} - ${retrievedNode.data.name}`);
// Output: Retrieved Node: CTO - Bob
The API also provides powerful methods for getting a node's children, its parent, or its entire ancestry path back to the root, making traversal simple and efficient.
Hierarchies change. Employees get promoted, product categories are renamed, and folder names are corrected. Updating a node's metadata is just as easy as creating it.
Let's say a new person, Carol, is hired as the CTO. We can update the existing CTO node's data field.
// 5. Update the data of an existing node
const updatedNode = await cto.update({
data: { ...cto.data, name: 'Carol' } // Keep the title, update the name
});
console.log(`Updated Node: ${updatedNode.data.title} - ${updatedNode.data.name}`);
// Output: Updated Node: CTO - Carol
The update method lets you modify the custom data without affecting the node's position in the tree structure, giving you complete flexibility.
With just these five API calls, you have the foundation for a powerful application built on hierarchical data. You've created a tree, added nodes, defined parent-child relationships, and updated data.
From here, you can explore more advanced features like:
Managing hierarchical data doesn't have to be a chore. By providing a dedicated API for tree data structures, tree.service.do lets you build with hierarchies, simply.
Ready to model your world? Sign up for free at tree.service.do and start building today