Folders

Folders are a central and highly flexible entity. They function as structured directories where folders can be nested within other folders, where various types of content to coexist within the same folder.

Folders in FoxNose CMS serve as a powerful tool for organizing and distributing content, making them essential for structuring data in a flexible yet efficient way. More than just a typical storage solution, folders allow users to group diverse data types, manage access, and streamline content distribution across different Delivery API configurations. This unique setup makes folders adaptable to various needs, whether organizing assets in plain folders or maintaining a structured dataset in collection folders.

Understanding Folders

Folders in FoxNose CMS are designed as central, highly flexible entities that go beyond traditional data storage. They serve as structured directories, where folders can be nested within each other and multiple content types can coexist within the same folder. This flexibility makes folders not only an intuitive way to organize data but also a powerful tool for content delivery.

With two folder types—plain folders and collection folders—FoxNose CMS provides distinct organizational options that allow you to structure content according to your specific needs. Plain folders support varied content and file types together, while collection folders enforce a consistent schema, ideal for structured data.

FoxNose CMS takes this further by enabling you to quickly generate APIs that mirror the folder hierarchy you’ve set up. By adding each folder to the API and setting permissions for specific actions, you can effortlessly create a fully functional, hierarchical API. This streamlined approach lets you set up and distribute content with precision, configure access rights, and manage actions per folder—all with minimal effort. The folder structure becomes the API structure, reflecting your content organization directly in the API routes and permissions.

Plain Folders

Plain folders are highly versatile. Within them, you can store diverse types of data and files side by side, even if the structures of the data are different. This flexibility is particularly useful when you have a small or moderate amount of data that doesn’t need to follow a uniform structure. To manage data structure, you can create templates within the folder or reference templates from another folder, allowing for varied document formats.

📁 Plain Folder A
├── 🎨 Templates
│   ├── Template 1
│   └── Template 2
│
├── 📄 Document A (Template 1)
├── 📄 Document B (Template 2)
├── 🖼️ Image File
├── 📼️ Video File
├── 📄 Document C (Template 1)
└── 📁 Plain Folder B
    └── 📄 Document D (Template 2)

Collection Folders

Collection folders ("collections") are structured with a single, unified data model, which is version-controlled. In these folders, all documents must adhere to this shared model, ensuring consistency across the data. Unlike plain folders, collection folders cannot reference templates from other sources; instead, they enforce a strict model across all documents, making them ideal for large datasets where every document follows the same format.

Each collection folder maintains only one versioned model, allowing updates to the data structure while preserving compatibility with existing documents. This versioning ensures that any changes to the model apply only to new entries or updates, while previously stored documents remain unchanged.

Additionally, collection folders can only contain other collection folders as children, maintaining uniform model requirements throughout the hierarchy and ensuring that all nested data follows a consistent structure.

📁 Collection Folder A (Model X)
├── 📄 Document 1 (Model X)
├── 📄 Document 2 (Model X)
└── 📁 Collection Folder B (Model Y)
    ├── 📄 Document 3 (Model Y)
    └── 📄 Document 4 (Model Y)

Strict Referencing In Collections

The strict reference system is a powerful tool that establishes ownership between documents across collections. This is similar to a foreign key (many-to-one) relationship in relational databases, where one document acts as the “owner” of another document, ensuring a clear hierarchy of relationships.

For example, consider 📁 Folder A that contains 📄 Document 1, and 📁 Folder B (nested inside 📁 Folder A) that contains 📄 Document 2.

📁 Folder A
├── 📄 Document 1
└── 📁 Folder B
    └── 📄 Document 2

In this scenario, 📄 Document 2 is strictly owned by 📄 Document 1, and 📄 Document 1 is the parent or owner of 📄 Document 2.

📄 Document 1
└── 📄 Document 2

This relationship is enforced via the strict reference system.

The strict reference system is essential for two reasons:

1. API Structure: It enables the creation of a structured API for content delivery. In this case, the API endpoints would look something like

https://7c9h4pwu.fxns.io/.../a/1/b/2

where the path reflects the strict ownership between the documents.

When retrieving data, the system checks that 📄 Document 2 exists in 📁 Folder B and that it is owned by 📄 Document 1, which resides in 📁 Folder A. This ensures the integrity of the data hierarchy.

2. Efficient Search: The strict reference system also allows for efficient searching of related documents without needing additional filters. For instance, querying

https://7c9h4pwu.fxns.io/.../a/1/b

would return all documents in 📁 Folder B that are strictly related to 📄 Document 1. This simplifies retrieving nested or related content and enables building comprehensive, hierarchical API structures.

In summary, the strict reference system allows for building clear relationships between documents and enables flexible, powerful API structures, making content retrieval more intuitive and efficient.

Folder API Model

Create Folder

curl https://api.foxnose.net/v1/7c9h4pwu/folders/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"name": "Sample Folder",
"parent": "6b4qd369",
"api_key_plural": "sample_folders",
"api_key_singular": "sample_folder",
"strict_reference": true,
"folder_type": "collection",
"content_type": "document"
}'

{
    "key": "0k96dpkn",
    "name": "Sample Folder",
    "parent": "6b4qd369",
    "api_key_plural": "sample_folders",
    "api_key_singular": "sample_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "created_at": "2024-10-29T07:02:53.215453-05:00"
}

List All Folders

curl https://api.foxnose.net/v1/7c9h4pwu/folders/?created_at__gte=2024-10-28&parent=6b4qd369 \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

{
    "count": 8,
    "next": null,
    "previous": null,
    "results": [
{
    "key": "0k96dpkn",
    "name": "Sample Folder",
    "parent": "6b4qd369",
    "api_key_plural": "sample_folders",
    "api_key_singular": "sample_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "created_at": "2024-10-29T07:02:53.215453-05:00"
},
{
    "key": "1m57gqrs",
    "name": "Assets Folder",
    "parent": "8v9kc483",
    "api_key_plural": "sample_assets",
    "api_key_singular": "sample_asset",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "asset",
    "created_at": "2024-11-02T12:14:21.482935-05:00"
}
    ],
}

Retrieve Folder

curl https://api.foxnose.net/v1/7c9h4pwu/folders/0k96dpkn/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

{
    "key": "0k96dpkn",
    "name": "Sample Folder",
    "parent": "6b4qd369",
    "api_key_plural": "sample_folders",
    "api_key_singular": "sample_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "created_at": "2024-10-29T07:02:53.215453-05:00"
}

Update Folder

curl https://api.foxnose.net/v1/7c9h4pwu/folders/0k96dpkn/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Sample Folder",
"api_key_plural": "sample_folders",
"api_key_singular": "sample_folder"
}'

{
    "key": "0k96dpkn",
    "name": "Updated Sample Folder",
    "parent": "6b4qd369",
    "api_key_plural": "sample_folders",
    "api_key_singular": "sample_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "created_at": "2024-10-29T07:02:53.215453-05:00"
}

Delete Folder

curl https://api.foxnose.net/v1/7c9h4pwu/folders/0k96dpkn/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

List Ancestor Folders

curl https://api.foxnose.net/v1/7c9h4pwu/folders/0k96dpkn/ancestors/?created_at__gte=2024-10-28 \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
{
    "key": "6b4qd369",
    "name": "Sample Folder",
    "parent": null,
    "api_key_plural": "sample_folders",
    "api_key_singular": "sample_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "created_at": "2024-10-29T07:02:53.215453-05:00"
},
{
    "key": "1m57gqrs",
    "name": "Assets Folder",
    "parent": "6b4qd369",
    "api_key_plural": "sample_assets",
    "api_key_singular": "sample_asset",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "asset",
    "created_at": "2024-11-02T12:14:21.482935-05:00"
}
    ]
}

List Children Folders

curl https://api.foxnose.net/v1/7c9h4pwu/folders/6b4qd369/children/?created_at__gte=2024-10-28 \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
{
    "key": "0k96dpkn",
    "name": "Sample Folder",
    "parent": "6b4qd369",
    "api_key_plural": "sample_folders",
    "api_key_singular": "sample_folder",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "document",
    "created_at": "2024-10-29T07:02:53.215453-05:00"
},
{
    "key": "1m57gqrs",
    "name": "Assets Folder",
    "parent": "6b4qd369",
    "api_key_plural": "sample_assets",
    "api_key_singular": "sample_asset",
    "strict_reference": true,
    "folder_type": "collection",
    "content_type": "asset",
    "created_at": "2024-11-02T12:14:21.482935-05:00"
}
    ]
}