Designing Content APIs with Flux

Once you've modeled your content using Folders, the next step is delivering it to your applications. FoxNose Flux APIs provide a powerful solution for this by allowing you to create multiple, independent APIs from a single content source. This gives you precise control over what content is exposed, who can access it, and the resulting URL structure.

What is a Flux API?

A Flux API is a high-performance, read-only endpoint optimized for content delivery. It sits completely separate from the Management API, which is used to create and edit your content.

Key Features:

  • Purpose-Built for Delivery: Optimized for fast, scalable, and secure content retrieval for your applications, websites, and services.
  • Multiple APIs, One Source: Create any number of distinct APIs within a single environment (e.g., an API for your blog, one for your shop, and another for docs), all pulling from the same content repository.
  • Data Model as API: The API structure is not arbitrary; it's a direct reflection of your folder hierarchy, making your endpoints logical and predictable.
  • Flexible Access Control: Can be fully public, require an API key, and grants access on a per-folder, per-method (get_one/get_many) basis.

Controlling Your API Endpoints: Structure and URLs

Every Flux API you create is identified by a unique prefix. This prefix defines the primary segment of your API's URL structure for content delivery.

The general pattern for Flux API endpoints is:

URL Pattern

https://<ENVIRONMENT_KEY>.fxns.io/<API_PREFIX>/<FOLDER_PATH>/[<RESOURCE_KEY>]

Where:

  • <ENVIRONMENT_KEY>: Your unique environment identifier.
  • <API_PREFIX>: The unique identifier for this specific Flux API (e.g., ai-skills-v1, legal-kb).
  • <FOLDER_PATH>: The hierarchical path generated by your connected folders (e.g., tools/data-analysis, regulations/gdpr).
  • [<RESOURCE_KEY>]: The optional key for an individual content item within a folder.

Examples

AI Agent Skill Catalog API: Define an ai-skills-v1 API prefix.

https://<ENVIRONMENT_KEY>.fxns.io/ai-skills-v1/tools/                                # All tools
https://<ENVIRONMENT_KEY>.fxns.io/ai-skills-v1/tools/{tool_key}                       # A specific tool
https://<ENVIRONMENT_KEY>.fxns.io/ai-skills-v1/tools/data-analysis/actions/           # Actions for 'data-analysis' tool
https://<ENVIRONMENT_KEY>.fxns.io/ai-skills-v1/tools/data-analysis/actions/{action_key} # A specific action

Regulatory Knowledge Base API: Define a legal-kb prefix.

https://<ENVIRONMENT_KEY>.fxns.io/legal-kb/regulations/                               # All regulations
https://<ENVIRONMENT_KEY>.fxns.io/legal-kb/regulations/gdpr/articles/                 # Articles under GDPR regulation
https://<ENVIRONMENT_KEY>.fxns.io/legal-kb/regulations/gdpr/articles/{article_key}    # A specific article

Exposing Content via Flux API

Once your Flux API is defined, the next step is to select which content it will serve. This is done by connecting folders to your API using the Management API. Only content from connected folders becomes accessible through that specific Flux API.

How it Works:

  1. Choose a Flux API: Decide which of your Flux APIs (identified by its prefix) will expose the content.
  2. Select Folders: Pick the folders (Collection or Composite) that contain the content you want to deliver.
  3. Define Permissions: For each connected folder, you specify exactly what operations are allowed (e.g., list resources, get single resource).
  4. Instant Delivery: Once connected, the content becomes immediately available through your Flux API endpoints, respecting the folder's hierarchy.

See the detailed guide here

The Role of Your Folder Hierarchy

The API structure automatically mirrors your folder hierarchy. Endpoint paths are generated using the alias property of connected folders, ensuring meaningful and consistent URL paths. For a deeper understanding of how folder hierarchies translate into API URLs, including the power of strict_reference, refer to the Folders guide.

Controlling Access: Permissions and allowed_methods

A key aspect of designing your Flux APIs is controlling exactly what content is accessible and how. When connecting folders, you define permissions using allowed_methods to control the available operations. This ensures that your APIs expose only what's intended.

Available Methods:

Granular Control with allowed_methods

By combining these methods, you gain fine-grained control:

  • "allowed_methods": ["get_many", "get_one"] → Full Access: Allows both listing/searching and retrieving individual resources.
  • "allowed_methods": ["get_many"] → Discoverability Only: Allows listing/searching resources. By default, only _sys metadata (keys, timestamps) is returned, making content discoverable without revealing full data. This is ideal for scenarios where you want to expose a catalog of items without showing their full details until explicitly requested via get_one.
  • "allowed_methods": ["get_one"] → Direct Access Only: Allows retrieving individual resources by key, but not listing or searching.
  • "allowed_methods": [] → URL Structure Only: The folder path is part of the API's URL structure, but no content can be accessed through it. Useful for building hierarchical URLs without exposing data from intermediate folders.

Folder Hierarchy and strict_reference

The way your folders are nested is crucial, especially when using the strict_reference setting. This powerful feature automatically constructs logical, hierarchical URLs for your API endpoints.

For a detailed explanation of folder hierarchy and the strict_reference feature, including examples of how it ensures data integrity and simplifies API design, please refer to the Folders guide.

Common Flux API Delivery Patterns

Flux APIs are highly flexible and can be configured to support various content delivery patterns, ranging from simple lists to complex, hierarchical knowledge bases.

Pattern 1: AI Agent Tool Catalog

Use Case: Exposing a flat list of tools or actions for an AI agent.

📁 Tools (connected with ["get_many", "get_one"])

Endpoints:

  • GET /ai-tools/tools/ - List all tools
  • POST /ai-tools/tools/_search - Search tools
  • GET /ai-tools/tools/{tool_key}/ - Get specific tool

Pattern 2: Categorized Knowledge Base

Use Case: Organizing knowledge by category (e.g., product features, FAQs, regulatory topics).

📁 Categories (connected with ["get_many"])
└── 📁 Articles (connected with ["get_many", "get_one"])

Endpoints:

  • GET /knowledge-base/categories/ - List all categories (identifiers only)
  • GET /knowledge-base/categories/:category_key/articles/ - List articles in a specific category
  • GET /knowledge-base/categories/:category_key/articles/{article_key}/ - Get a specific article

Pattern 3: Multi-level Hierarchical Data

Use Case: Delivering deeply nested, context-dependent information (e.g., a legal code, scientific classifications).

📁 Regulations (connected with ["get_many"])
└── 📁 Chapters (connected with ["get_many"])
    └── 📁 Sections (connected with ["get_many", "get_one"])

Endpoints:

  • GET /legal-code/regulations/ - List regulations
  • GET /legal-code/regulations/:reg_key/chapters/ - List chapters in a regulation
  • GET /legal-code/regulations/:reg_key/chapters/:chapter_key/sections/ - List sections in a chapter
  • GET /legal-code/regulations/:reg_key/chapters/:chapter_key/sections/{section_key}/ - Get a specific section

Best Practices for Flux API Design

Designing powerful and secure Flux APIs requires thoughtful planning. Here are some key recommendations:

API Design Strategies

  • Meaningful Prefixes: Choose descriptive API prefixes (e.g., ai-skills-v1, legal-kb) that clearly indicate the API's purpose.
  • Folder Structure First: Design your folder hierarchy to directly reflect your desired API structure. Your data model is your API.
  • Consistent Aliases: Use clear, consistent, and often plural aliases for folders (articles, tools, regulations) as they form your API endpoint segments.
  • Leverage strict_reference: For truly dependent data (e.g., comments for a post), use strict_reference in nested folders to enforce data integrity and create clean, hierarchical API paths.
  • Principle of Least Privilege: Grant only the necessary allowed_methods for each connected folder. If an application only needs to read single items, don't grant get_many.

Your Next Steps

Ready to bring your content to life with Flux APIs? Here's how to continue:

You've got the blueprint; now it's time to build!

Was this page helpful?