Routing Management

Routing Management lets you create custom API endpoints that are served by your backend server. By default, Enfyra automatically generates REST API endpoints for every table you create (like /table_definition). The Routing Manager allows you to create custom endpoints like /products or /users for any purpose you need.

Important: All routes are created and served by the backend server, not the frontend app. The frontend consumes these API endpoints via HTTP requests.

Route Properties

Basic Configuration

• Path: The custom endpoint path (e.g., /assets/:id instead of /file_definition)
• Icon: Visual identifier for the route (using Lucide icons)
• Description: Human-readable description of the route's purpose
• Status: Whether the route is enabled or disabled
• System Route: Indicates if this is a core system route

Advanced Configuration

• Main Table: The primary table this route serves (see below for details)
• Available Methods: Method records this route supports. Method labels live in method_definition.name; manage method records and badge colors from Settings > Methods.
• Route Permissions: Access control rules for this endpoint
• Handlers: Custom request processing logic (see Custom Handlers)
• Hooks: Lifecycle events and custom processing (Pre-Hooks and Post-Hooks)
• Published Methods: Defines which HTTP methods are public (no authentication required) vs private (role-protected)

Creating Custom Routes

Step 1: Access Route Manager

1. Navigate to Settings > Routes
2. Click "Create Route" button

Step 2: Basic Configuration

Configure the essential route properties: - Path: Set your custom endpoint (e.g., /v1/products, /user-profiles) - Icon: Choose a Lucide icon for visual identification - Description: Add a clear description of the route's purpose - Is Enabled: Toggle to activate the route - Available Methods: Select the methods the route supports. If a method is missing, open Settings > Methods or use the selector + action to create it.

See Method Management for method records and badge color configuration.

Step 3: Link to Main Table

The most important step is connecting your route to a data source: 1. Click the relation picker (pencil icon) next to Main Table 2. Search and select the table this route should serve 3. Automatic CRUD Operations: Once linked, your custom route can provide: - GET /your-route - List all records - POST /your-route - Create new record - PATCH /your-route/:id - Update record - DELETE /your-route/:id - Delete record

1. Published Methods Control: HTTP methods specified in Published Methods become public (accessible by guests without authentication). Methods not listed remain private and require proper authentication and role permissions.

The route inherits all the table's fields, validation rules, and relationships without requiring additional configuration.

See Relation Picker System for detailed usage of the relation selection interface.

Step 4: Save and Test

1. Click Save to create the route
2. The custom endpoint becomes active immediately
3. All data management pages automatically use the new endpoint
4. API calls throughout the system switch to the custom path

Step 5: Configure Execution Flow (Handlers & Hooks)

After creating a route, you can configure the execution flow with handlers and hooks. The Execution Flow Visualization section provides a visual representation of how requests are processed for each HTTP method.

Understanding Execution Flow

The execution flow shows the sequence of: 1. Pre-Hooks (executed before the handler, in priority order) 2. Handler (the main processing logic, or default CRUD if no custom handler) 3. Post-Hooks (executed after the handler, in priority order)

Main Table and Default Handler

When a route has a Main Table configured: - If no custom handler exists for a specific HTTP method, the system automatically uses the default handler that provides standard CRUD operations - The default handler appears in the execution flow visualization for all methods that don't have a custom handler - You can click on the default handler to create a custom handler for that method

Adding Handlers

1. In the route detail page, scroll to the Execution Flow section
2. Click "Add Handler" button
3. Configure the handler:
4. Name: Descriptive name for the handler
5. Method: Select the HTTP method record this handler processes. Built-in CRUD methods are GET, POST, PATCH, and DELETE; custom methods such as PUT must exist in Settings > Methods first.
6. Logic: Write your custom JavaScript code
7. Is Enabled: Toggle to activate/deactivate
8. Click Save to create the handler

Note: When a custom handler exists for a method, it replaces the default CRUD handler for that specific method.

Adding Hooks

Hooks allow you to add processing logic before (Pre-Hooks) or after (Post-Hooks) the handler execution.

Pre-Hooks - Execute before the handler: 1. Click "Add Pre-Hook" button 2. Configure the hook: - Name: Descriptive name - Is Global: Check this to apply the hook to all routes (not just this route) - Methods: Select which HTTP method records this hook applies to (can select multiple) - Priority: Lower numbers execute first (e.g., 1 executes before 2) - Logic: Write your JavaScript code - Is Enabled: Toggle to activate/deactivate 3. Click Save

Post-Hooks - Execute after the handler: 1. Click "Add Post-Hook" button 2. Configure the same fields as Pre-Hooks 3. Click Save

Global Hooks: - When Is Global is enabled, the hook applies to all routes in the system - Global hooks appear in the execution flow for matching route methods - Use global hooks for cross-cutting concerns like logging, authentication checks, or notifications that should run for every request

Visual Execution Flow

The execution flow visualization: - Groups execution by HTTP method (GET, POST, PATCH, DELETE) - Shows the sequence of Pre-Hooks > Handler > Post-Hooks for each method - Displays hook priority numbers - Allows clicking on any node to edit it - Shows enabled/disabled status

Hook Display Rules: - Global hooks (isGlobal = true) appear for matching route methods - Method-specific hooks appear only for their selected methods - Default handler appears for all methods that don't have a custom handler (when Main Table is configured)

Editing and Managing

• Click any node in the visualization to edit it
• Delete nodes directly from the edit interface
• Enable/Disable hooks without editing them
• Changes take effect immediately

Step 6: Configure Route Permissions (Optional)

After creating the route, you can set up fine-grained access control:

1. Access the edit page of your newly created route
2. Scroll to Route Permissions section (only available on edit page, not during creation)
3. Click "Add Permission" to open the permission configuration drawer
4. Configure permission settings:
5. Role: Select which role gets access (single selection via relation picker)
6. Methods: Choose which REST methods this role can access (multiple selection): GET, POST, PATCH, DELETE
7. Allowed Users: Select specific users who bypass role restrictions (multiple selection via relation picker)
8. Is Enabled: Toggle to activate/deactivate this permission rule

9. Description: Document the purpose of this permission

10. Save the permission - it takes effect immediately

Important: Route Permissions operate independently from the main route configuration. Changes to permissions (create, edit, delete) are applied instantly without requiring the "Save" button in the header actions.

Managing Route Permissions

After creating permissions, they appear as a list in the Route Permissions section: - Permission entries display the description (or "No description" if empty) - Status indicator shows if the permission is enabled or disabled - Actions include edit and delete options for each permission - Multiple permissions can be configured for the same route with different roles/methods - Instant updates: All permission changes take effect immediately, separate from route modifications

See Relation Picker System for details on selecting roles and users through the relation interface.

GraphQL Access

GraphQL is enabled per table from the table editor with the GraphQL toggle, which writes the table's gql_definition record. It is not enabled from Route Permissions.

GraphQL requests currently require a Bearer token. REST publishedMethods and route permission methods do not make GraphQL anonymous. GraphQL queries and mutations still use the same table metadata, field publication state, generated input/output schema, guards, and repository behavior as the server runtime.

For query syntax and filters, see Query Filtering.

System Routes

System routes (marked with "System Route" badge) are core Enfyra endpoints that power the admin interface. These routes are automatically created and should generally not be modified unless you understand the implications.

Examples include routes for: - File and storage management - Route definition management - Menu configuration - User and permission systems

Method Publishing and Access Control

The Published Methods field controls the authentication requirements for each HTTP method.

For complete details on permissions, roles, and allowedUsers, see Permission Builder.

Published Methods vs Private Methods

• Published Methods: Public access, no authentication required
• Unpublished Methods: Require authentication and proper permissions

Quick Reference

1. Published Methods: Public access
2. Allowed Users: Bypass role restrictions
3. Role Permissions: Standard role-based access
4. No Access: Denied

Custom Route Behavior

Default CRUD Operations

When you create a route and link it to a Main Table, Enfyra automatically provides standard CRUD operations:

REST API: - GET /your-route - List records - POST /your-route - Create record - PATCH /your-route/:id - Update record - DELETE /your-route/:id - Delete record

GraphQL API: - query { your_table(...) } - Query records - mutation { create_your_table(...) } - Create record - mutation { update_your_table(...) } - Update record - mutation { delete_your_table(...) } - Delete record

Custom Handlers Override

You can replace any of these default operations with custom business logic by creating handlers:

1. Create the route with Main Table configured
2. Add custom handlers via the Execution Flow section to override specific HTTP methods
3. Handler takes precedence - when a handler exists for a route+method, it executes instead of default CRUD

For detailed handler creation and examples, see Custom Handlers.

Route Status

• Enabled/Disabled: Controls whether the route is active
• System Integration: System routes are automatically integrated with the admin interface

Custom Endpoint Benefits

API Consistency

Create RESTful endpoints that match your application's naming conventions: - /products instead of /table_definition - /orders instead of /order_table

Versioning Support

Implement API versioning: - /v1/users - /v2/users

Business Logic Integration

Routes can be enhanced with: - Custom validation through handlers - Data transformation via hooks - Specialized permission rules

Impact on Data Pages

When you create custom routes, all related functionality automatically adapts: - Data management pages use the custom endpoint - Relation pickers respect custom routes - Permission systems apply to custom paths - API calls throughout the system use the new endpoints

Changes to routes take effect immediately without requiring application restart.

Best Practices

Naming Conventions

• Use lowercase, hyphen-separated paths: /user-profiles
• Include version prefixes for API stability: /v1/
• Be descriptive but concise: /product-categories not /pc

Route Organization

• Group related routes under common prefixes
• Use consistent patterns across your API
• Document the purpose of each custom route

Permission Alignment

• Ensure route permissions align with table permissions
• Test custom routes with different user roles
• Consider the security implications of custom paths

Execution Flow Organization

• Use Pre-Hooks for validation, authentication checks, or data preparation
• Use Handlers for the main business logic
• Use Post-Hooks for logging, notifications, or cleanup
• Set appropriate priority values to control execution order
• Use Global Hooks sparingly for cross-cutting concerns that apply to all routes

Related Documentation

• Custom Handlers - Writing JavaScript logic for custom endpoints
• Hooks System - Adding validation and notifications
• Package Management - Installing NPM packages for external integrations

Practical Examples

• User Registration Example - Complete walkthrough including route creation, custom handler, and nodemailer integration