Build Flux APIs

API Reference: Building Flux APIs | Flux API Reference

In FoxNose, you have the flexibility to create multiple Flux APIs within a single environment. Each API represents a specific set of connected folders from which you can distribute content to your applications. This allows for granular control over which content is exposed and how it's organized for public consumption.

Understanding Flux APIs

Flux APIs are content delivery endpoints that provide public access to your structured content. Unlike the Management API which is designed for content management, Flux APIs are optimized for content consumption by your applications, websites, and services.

Key Characteristics

  • Public Access: Designed for public content delivery (authentication is optional)
  • Read-Only: Focused on content retrieval operations (get_one, get_many, search)
  • Performance Optimized: Built for high-performance content delivery
  • Flexible Structure: Mirror your folder hierarchy in URL structure

API Structure and URLs

Each Flux API has a unique prefix that serves as the starting point for its URL structure. This helps differentiate between multiple APIs within the same environment and provides meaningful namespacing for your content.

URL Pattern

https://<ENVIRONMENT_KEY>.fxns.io/<API_PREFIX>/<FOLDER_PATH>/

Examples

Blog API:

https://7c9h4pwu.fxns.io/blog-v1/articles/
https://7c9h4pwu.fxns.io/blog-v1/categories/tech/articles/

E-commerce API:

https://7c9h4pwu.fxns.io/shop-v1/products/
https://7c9h4pwu.fxns.io/shop-v1/categories/electronics/products/

Folder Connections

After creating a Flux API, you connect folders to it using the Management API. Only data from connected folders will be accessible through the Flux API.

Connection Process

  1. Create Flux API with unique prefix
  2. Connect folders to the API
  3. Configure permissions for each folder
  4. Test endpoints using Flux API

URL Structure Generation

The API structure mirrors your folder hierarchy. Endpoint paths are generated using the alias property of connected folders, ensuring meaningful and consistent URL paths.

📁 Categories (alias: "categories")
└── 📁 Electronics (alias: "electronics") 
    └── 📁 Products (alias: "products")

Results in URLs:

/api_prefix/categories/
/api_prefix/categories/:category_key/electronics/
/api_prefix/categories/:category_key/electronics/:electronics_key/products/

Permissions and Access Control

When connecting folders to a Flux API, you specify allowed_methods that control what operations are available:

Available Methods

Permission Combinations

{
  "allowed_methods": ["get_many", "get_one"]  // Full access
}

{
  "allowed_methods": ["get_many"]  // List/search only (returns identifiers)
}

{
  "allowed_methods": ["get_one"]  // Individual resource access only
}

{
  "allowed_methods": []  // URL structure only (no data access)
}

When only get_many is enabled without get_one, the API returns identifiers only to protect content while allowing resource discovery.

Inheritance and Folder Hierarchy

Automatic Folder Inclusion with strict_reference

When you connect a folder with strict_reference enabled, FoxNose automatically includes certain ancestor folders in the API's URL structure:

How It Works:

  1. Chain of strict_reference Folders: Only ancestor folders with strict_reference enabled are automatically included
  2. Stops at Non-strict_reference Folders: Inclusion stops when encountering folders without strict_reference
  3. URL Structure Only: Auto-included folders have allowed_methods: [] (no data access)
  4. Explicit Connection Required: To serve content from ancestor folders, explicitly connect them with desired permissions

Example Scenario

📁 Blog (strict_reference: false)
└── 📁 Articles (strict_reference: false)
    └── 📁 Categories (strict_reference: true)
        └── 📁 Tech (strict_reference: true)
            └── 📄 Article 1

If you connect only the "Tech" folder:

  • Categories is automatically included (has strict_reference: true)
  • Articles and Blog are skipped (no strict_reference)

Resulting URLs:

/api_prefix/categories/:category_key/tech/           # List tech articles
/api_prefix/categories/:category_key/tech/:key/      # Get specific article

Accessing /api_prefix/categories/ directly:

  • Returns "Action Not Allowed" error (no allowed_methods configured)
  • Categories serves as URL structure only

Benefits of This Approach

  • Accurate URL Paths: Reflects true content hierarchy
  • Controlled Access: Maintain security by explicitly configuring data access
  • Clean URLs: Skips irrelevant hierarchy levels
  • Flexible Structure: Support complex nested content relationships

Content Delivery Patterns

Pattern 1: Simple Content API

Use Case: Blog, news site, or documentation

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

Endpoints:

  • GET /blog-v1/articles/ - List articles
  • POST /blog-v1/articles/_search - Search articles
  • GET /blog-v1/articles/:key/ - Get specific article

Pattern 2: Categorized Content

Use Case: E-commerce, knowledge base

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

Endpoints:

  • GET /shop-v1/categories/ - List categories (identifiers only)
  • GET /shop-v1/categories/:category_key/products/ - List products in category
  • GET /shop-v1/categories/:category_key/products/:key/ - Get specific product

Pattern 3: Multi-level Hierarchy

Use Case: Complex content structures

📁 Regions (connected with ["get_many"])
└── 📁 Cities (connected with ["get_many"]) 
    └── 📁 Venues (connected with ["get_many", "get_one"])

Endpoints:

  • GET /api/regions/ - List regions
  • GET /api/regions/:region_key/cities/ - List cities in region
  • GET /api/regions/:region_key/cities/:city_key/venues/ - List venues in city
  • GET /api/regions/:region_key/cities/:city_key/venues/:key/ - Get specific venue

Best Practices

API Design

  1. Use Meaningful Prefixes: Choose descriptive API prefixes (blog-v1, shop-api, docs-v2)
  2. Plan Folder Structure: Design folder hierarchy with API consumption in mind
  3. Configure alias: Use clear, consistent plural names for endpoints
  4. Leverage strict_reference: Use for enforcing proper content relationships

Security and Performance

  1. Minimal Permissions: Only grant necessary allowed_methods for each folder
  2. Use Identifiers Pattern: For sensitive content, use get_many only to return identifiers

Next Steps

  1. Create Your First Flux API: Use the Management API to create and configure APIs
  2. Connect Folders: Add folders with appropriate permissions
  3. Implement Authentication: Configure API key authentication if needed

Was this page helpful?