Modern applications are a far cry from the static, monolithic systems of the past. Today, users expect real-time updates, seamless collaboration, and instant notifications. But what about the underlying file and directory structures that power these applications? Too often, they remain static and disconnected, requiring constant polling and complex logic to integrate into dynamic, event-driven architectures.
What if your file system could actively participate in your application's workflow? Imagine a directory structure that could instantly notify your services when a new file is uploaded, a user's permissions are changed, or a folder is deleted.
This is where the power of an API-first approach comes in. By combining the programmatic control of the directories.do API with the real-time notifications of webhooks, you can build a secure, reactive, and highly scalable file management system that is truly event-driven.
In this guide, we'll walk through how to build a proof-of-concept for a secure file-sharing system that responds to directory changes in real-time.
ORGANIZE. AUTOMATE. SCALE.
Traditional file systems are often rigid. Managing them usually involves manual processes or brittle scripts. An API-first approach, however, treats your directory structure as a programmable resource. Instead of just storing files, you can turn directory operations into automated, code-driven workflows.
This unlocks several key advantages:
This concept is the core of directories.do—providing you with the tools to build sophisticated, agentic workflows where the directory system is an active agent in your application's processes.
To build our event-driven system, we need two key components:
directories.do API: This will be our "source of truth" for the directory structure. We'll use it to programmatically create folders, attach security metadata, and manage the hierarchy. Its power lies in treating every directory as a structured data object.
Webhooks: These are the messengers. A webhook is simply an automated message (an HTTP POST request) sent from one app to another when a specific event occurs. In our case, directories.do will send a webhook to our application whenever a directory is created, updated, or deleted.
When combined, directories.do manages the state, and webhooks communicate the state changes.
Let's build a system where creating a new user document directory automatically triggers a notification and an audit log entry.
First, we need a logical structure. A common pattern is to organize directories by team and user. For example: /teams/{teamId}/users/{userId}/documents.
The real power comes from the metadata. With directories.do, we can attach a JSON object to any directory to store custom information. We'll use this to manage permissions.
Here’s how you'd create a secure user directory using the API:
import { Directories } from '@do-sdk/core';
// Initialize the Directories agent
const directoryService = new Directories();
// Create a new user directory with metadata for access control
const newUserDirectory = await directoryService.create({
path: '/teams/engineering/users/jane.doe/documents',
metadata: {
ownerId: 'user-id-12345',
accessControl: ['user-id-12345', 'admin-id-987'],
status: 'active'
},
recursive: true // Creates parent directories if they don't exist
});
console.log('Successfully created directory:', newUserDirectory.path);
In this example, the metadata object clearly defines who owns the directory and who has access. Your application's business logic can now use this metadata to enforce security rules on every subsequent API call.
Next, we need an endpoint in our application to "catch" the notifications from directories.do. This is a simple server that listens for incoming HTTP POST requests.
Here's a basic example using Node.js and Express:
import express from 'express';
const app = express();
app.use(express.json()); // Middleware to parse JSON bodies
const PORT = 3000;
// This is our webhook listener endpoint
app.post('/webhooks/directories', (req, res) => {
const event = req.body;
console.log(`Received event: ${event.type}`);
// Handle the event based on its type
switch (event.type) {
case 'directory.created':
const newDirectory = event.data;
console.log(`New directory created at path: ${newDirectory.path}`);
// --- Trigger reactive workflows here ---
// 1. Send a Slack notification
// sendSlackNotification(`New folder created: ${newDirectory.path}`);
// 2. Add to an audit log
// logAuditEvent('directory_created', { user: 'system', path: newDirectory.path });
break;
case 'directory.deleted':
// Handle deletion events
break;
// Add more cases for other events
}
res.status(200).send('Event received');
});
app.listen(PORT, () => {
console.log(`Webhook listener running on http://localhost:${PORT}`);
});
Once your listener is deployed, you just need to tell directories.do where to send the events. In your directories.do dashboard, you would navigate to the Webhooks section, add a new endpoint, and paste the URL of your listener (e.g., https://yourapp.com/webhooks/directories).
You can subscribe to specific events like directory.created, directory.updated, and directory.deleted to avoid unnecessary traffic.
Now, let's trace the complete workflow:
You've successfully built a system that reacts to file system changes instantly, without polling or complex state management.
By combining an API-first directory service with webhooks, you move beyond simple file storage. You create a dynamic, living system that is a core part of your application architecture. This approach enables you to build secure, scalable, and responsive features that would be incredibly complex with traditional file systems.
directories.do isn't just an API for creating folders; it's a foundational service for building powerful, automated, and code-driven workflows around any hierarchical data.
Ready to automate your directory operations? Explore our documentation and start building with directories.do today.
Q: What kind of directories can I manage with directories.do?
A: You can manage any type of hierarchical data structure. Common use cases include user directories, file systems, organizational charts, or product catalogs. The system is flexible by design and supports any nested data model.
Q: How does .do handle permissions and access control?
A: Permissions are handled via metadata attached to each directory entry. You can define granular access control lists (ACLs) or role-based access control (RBAC) policies that our platform enforces on every API call, ensuring your data remains secure.
Q: Is it possible to list or manage directory contents recursively?
A: Yes, our API supports recursive operations for listing, deleting, or modifying directories. You can specify depth and apply filters to efficiently manage complex nested structures with a single command.
Q: Can I store custom metadata with each directory?
A: Absolutely. Each directory entry can hold a flexible JSON object for metadata. This is ideal for storing application-specific information like user IDs, team affiliations, file types, or status flags, making your directory a powerful, integrated data source.