### Connection initialization YAML example

Source: https://github.com/datazoode/flapi/blob/main/docs/spec/components/query-execution.md

Example flapi.yaml configuration for a connection named postgres-db, with initialization SQL to install and load the postgres extension and attach a database, plus properties for host and database.

```yaml
connections:
  postgres-db:
    init: |
      INSTALL postgres;
      LOAD postgres;
      ATTACH 'host=localhost dbname=mydb' AS pg (TYPE postgres);
    properties:
      host: localhost
      database: mydb
```

--------------------------------

### Environment Variables in Include Paths - Syntax and Examples

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Shows how to use environment variables in include paths for dynamic configuration. Includes syntax, multiple examples, and the required environment setup commands.

```yaml
{{include from path/{{env.VARIABLE_NAME}}/file.yaml}}
```

```yaml
# Environment-specific configuration
{{include from config/{{env.ENVIRONMENT}}-database.yaml}}
{{include from config/{{env.ENVIRONMENT}}-auth.yaml}}

# Dynamic file selection
{{include from templates/{{env.TEMPLATE_TYPE}}.yaml}}
{{include from connections/{{env.DATA_SOURCE}}-connection.yaml}}

# Combined with section includes
{{include:auth from security/{{env.AUTH_PROVIDER}}-config.yaml}}
```

```bash
export ENVIRONMENT=production
export TEMPLATE_TYPE=advanced
export DATA_SOURCE=bigquery
export AUTH_PROVIDER=oauth2
```

--------------------------------

### Minimal flAPI quick start configuration

Source: https://github.com/datazoode/flapi/blob/main/docs/CONFIG_REFERENCE.md

Three files that together form the minimal flAPI setup: the main flapi.yaml, the endpoint definition customers.yaml, and the SQL template customers.sql. The SQL template uses Mustache-style placeholders for connection path and optional id parameter.

```yaml
# flapi.yaml
project-name: my-api

template:
  path: ./sqls

connections:
  local-data:
    properties:
      path: ./data/customers.parquet

duckdb:
  access_mode: READ_WRITE
```

```yaml
# sqls/customers.yaml
url-path: /customers
method: GET
template-source: customers.sql
connection:
  - local-data
```

```sql
-- sqls/customers.sql
SELECT * FROM read_parquet('{{{ conn.path }}}')
{{#params.id}}
WHERE id = {{ params.id }}
{{/params.id}}
LIMIT 100
```

--------------------------------

### Configuration File Examples

Source: https://github.com/datazoode/flapi/blob/main/docs/CLI_REFERENCE.md

Examples of using the -c/--config flag and FLAPI_CONFIG environment variable to specify configuration files.

```bash
# Use default flapi.yaml in current directory
./flapi

# Specify a custom configuration file
./flapi -c production.yaml
./flapi --config /etc/flapi/config.yaml

# Point at a config via environment variable (12-factor style)
export FLAPI_CONFIG=/etc/flapi/production.yaml
./flapi
```

--------------------------------

### Start the server with a config

Source: https://github.com/datazoode/flapi/blob/main/cli/Readme.md

Starts the flAPI server with a specified port and configuration file.

```bash
./build/release/flapi --port 8080 --config examples/flapi.yaml
```

--------------------------------

### Example: customers-rest.yaml

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/SQL_TESTER_INCLUDE_FIX.md

Example YAML file with includes that demonstrates the need for backend expansion.

```yaml
{{include:request from common/customer-common.yaml}}
{{include:auth from common/customer-common.yaml}}
{{include:rate-limit from common/customer-common.yaml}}

url-path: /customers/
method: GET
template-source: customers.sql
```

--------------------------------

### Directory Structure of Examples

Source: https://github.com/datazoode/flapi/blob/main/examples/README.md

Shows the layout of the examples directory, including configuration, data files, and endpoint configurations organized by tutorial.

```text
examples/
├── flapi.yaml              # Main configuration (connections, DuckDB settings, MCP config)
├── data/                   # Data files used by the examples
│   ├── customers.parquet   # TPC-H customer data (1500 rows)
│   └── northwind.sqlite    # Northwind sample database
└── sqls/                   # Endpoint configurations organized by topic
    ├── customers/          # Tutorial 2-3: Config reuse, validators, MCP
    ├── northwind/          # Tutorial 1: Basic REST CRUD
    ├── publicis/           # Tutorial 4: BigQuery + caching
    ├── sap/                # Tutorial 5: Enterprise integration
    ├── taxi/               # Advanced: AWS Secrets Manager (inactive)
    └── recommendations/    # Advanced: Composite keys (inactive)
```

--------------------------------

### flapii CLI Command Examples

Source: https://github.com/datazoode/flapi/blob/main/AGENTS.md

Example commands for the flapii CLI to manage endpoints, templates, and cache. Includes listing, getting, expanding, refreshing, validating, and creating endpoints.

```bash
# List all endpoints
flapii endpoints list

# Get specific endpoint config
flapii endpoints get /customers

# Test template expansion
flapii templates expand /customers --params '{"id":"123"}'

# Refresh cache for endpoint
flapii cache refresh /customers

# View cache configuration
flapii cache get /customers

# Validate endpoint YAML before creating
flapii endpoints validate sqls/new_endpoint.yaml

# Create endpoint from YAML file
flapii endpoints create sqls/new_endpoint.yaml
```

--------------------------------

### Quick Start: Run flAPI server

Source: https://github.com/datazoode/flapi/blob/main/examples/README.md

Starts the flAPI server from the project root. The server listens on http://localhost:8080 and exposes an MCP endpoint at http://localhost:8080/mcp/jsonrpc.

```bash
# From the project root
./build/release/flapi --config examples/flapi.yaml

# Server starts at http://localhost:8080
# MCP endpoint at http://localhost:8080/mcp/jsonrpc
```

--------------------------------

### flapi info example output

Source: https://github.com/datazoode/flapi/blob/main/docs/CLI_REFERENCE.md

Example output from `flapi info` showing bundle offset, size, and entry list. The output includes a placeholder for additional entries.

```bash
$ ./flapi-prod info
Binary: /opt/flapi/flapi-prod
Bundle offset: 70123456
Bundle size:   12534 bytes
Entries (17):
  flapi.yaml (1024 bytes)
  sqls/customers.yaml (412 bytes)
  ...
```

--------------------------------

### S3 Configuration and Start Command

Source: https://github.com/datazoode/flapi/blob/main/docs/features/vfs-cloud-storage.md

Set AWS credentials and start flAPI with an S3-hosted config file using the s3:// URL scheme.

```bash
# Set AWS credentials
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_REGION="us-east-1"

# Start flAPI with S3-hosted config
./flapi -c s3://my-bucket/path/to/flapi.yaml
```

--------------------------------

### Development Workflow Commands (make debug, run-debug, test-all, clean)

Source: https://github.com/datazoode/flapi/blob/main/AGENTS.md

Typical development cycle: use `make debug` for fast iterative builds, `make run-debug` to start the server with the example configuration, and after editing code rebuild with `make debug`. Before committing, run `make test-all` and `make clean`.

```bash
# Full development cycle
make debug                           # Fast iterative builds
make run-debug                       # Start server with examples
# Edit code and rebuild: make debug

# Before committing
make test-all                        # Run full test suite
make clean                           # Clean artifacts
```

--------------------------------

### SAP Connection Init Script in flapi.yaml

Source: https://github.com/datazoode/flapi/blob/main/examples/README.md

This YAML configuration defines a connection named 'sap-abap-trial' with an init script that installs and loads the 'erpl' extension, creates a persistent secret for SAP ABAP trial, and sets up the connection parameters. The init script runs SQL to set up extensions and credentials. This example requires a running SAP ABAP trial system.

```yaml
connections:
  sap-abap-trial:
    init: |
      INSTALL 'erpl' FROM 'http://get.erpl.io';
      LOAD 'erpl';

      CREATE OR REPLACE PERSISTENT SECRET abap_trial (
        TYPE sap_rfc,
        ASHOST 'localhost',
        SYSNR '00',
        CLIENT '001',
        USER 'DEVELOPER',
        PASSWD 'password',
        LANG 'EN'
      );
```

--------------------------------

### GCS Configuration and Start Command

Source: https://github.com/datazoode/flapi/blob/main/docs/features/vfs-cloud-storage.md

Set GCP credentials and start flAPI with a GCS-hosted config file using the gs:// URL scheme.

```bash
# Set GCP credentials
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export GOOGLE_CLOUD_PROJECT="my-project"

# Start flAPI with GCS-hosted config
./flapi -c gs://my-bucket/path/to/flapi.yaml
```

--------------------------------

### Install flAPI with uvx or pip

Source: https://github.com/datazoode/flapi/blob/main/Readme.md

Install flAPI and its CLI client. The package name is flapi-io because "flapi" is taken on PyPI. The uvx commands run the server and client without installation; pip installs both commands permanently.

```bash
# Run the flapi server (note: "flapi" is taken on PyPI, so the package is "flapi-io")
uvx --from flapi-io flapi -c flapi.yaml

# Run the flapii CLI client (also bundled in flapi-io)
uvx --from flapi-io flapii
```

```bash
pip install flapi-io   # installs both "flapi" and "flapii" commands
```

--------------------------------

### Complete flapi.yaml Configuration Example

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

A complete example of the main flapi.yaml file, covering project information, template configuration, database connections (BigQuery, Parquet, PostgreSQL), DuckDB settings, global rate limiting, HTTPS enforcement, and heartbeat configuration.

```yaml
# Project Information
project-name: enterprise-api
project-description: Enterprise data API with multiple sources
server-name: production-server

# Template Configuration
template:
  path: './sqls'
  environment-whitelist:
    - '^FLAPI_.*'
    - '^DB_.*'

# Database Connections
connections:
  # BigQuery connection
  bigquery-warehouse:
    init: |
      FORCE INSTALL 'bigquery' FROM 'http://storage.googleapis.com/hafenkran';
      LOAD 'bigquery';
    properties:
      project_id: 'my-gcp-project'
      dataset: 'analytics'
    log-queries: true
    log-parameters: false
    allow: '*'

  # Parquet files
  customer-data:
    properties:
      path: './data/customers.parquet'
    log-queries: false

  # PostgreSQL connection
  postgres-orders:
    init: |
      INSTALL postgres_scanner;
      LOAD postgres_scanner;
    properties:
      host: 'localhost'
      port: '5432'
      database: 'orders'
      user: 'flapi_user'
      password: '${DB_PASSWORD}'

# DuckDB Configuration
duckdb:
  db_path: ./enterprise_cache.db
  access_mode: READ_WRITE
  threads: 8
  max_memory: 8GB
  default_order: DESC

# Global Rate Limiting
rate-limit:
  enabled: true
  max: 1000
  interval: 3600  # 1 hour

# HTTPS Configuration
enforce-https:
  enabled: true
  ssl-cert-file: './ssl/cert.pem'
  ssl-key-file: './ssl/key.pem'

# Global Heartbeat
heartbeat:
  enabled: true
  worker-interval: 30
```

--------------------------------

### flapi unpack example with diff

Source: https://github.com/datazoode/flapi/blob/main/docs/CLI_REFERENCE.md

Example of unpacking a bundle and diffing it against a source tree. The output shows the unpacked entries and a diff command that produces no output when matching.

```bash
$ ./flapi-prod unpack --to /tmp/extracted
Unpacked 17 entries to /tmp/extracted

$ diff -ru ./examples /tmp/extracted
# (empty -- bundle matches source tree)
```

--------------------------------

### Install build dependencies

Source: https://github.com/datazoode/flapi/blob/main/Readme.md

Installs the required system packages for building flAPI: build-essential, cmake, and ninja-build.

```bash
sudo apt-get install -y build-essential cmake ninja-build
```

--------------------------------

### Start flapi with config service

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/API_CLIENT_REFACTORING_COMPLETE.md

Starts the flapi server with the config service enabled and a token for authentication. Used as the first step before testing the SQL template tester.

```bash
./build/release/flapi --config examples/flapi.yaml \
  --config-service \
  --config-service-token test1234567890123456789012345678
```

--------------------------------

### Basic File Include - Syntax and Example

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Covers the basic file include directive. The example shows main.yaml including two files, with the resulting merged YAML. Note that the result uses underscores in project_name while the source uses hyphens.

```yaml
{{include from file_path}}
```

```yaml
# main.yaml
project-name: my-project
{{include from common/database-config.yaml}}
{{include from common/auth-config.yaml}}

# common/database-config.yaml
connections:
  main-db:
    properties:
      path: './data/main.parquet'

# common/auth-config.yaml  
auth:
  enabled: true
  type: basic
  users:
    - username: admin
      password: secret
```

```yaml
project_name: my-project
connections:
  main-db:
    properties:
      path: './data/main.parquet'
auth:
  enabled: true
  type: basic
  users:
    - username: admin
      password: secret
```

--------------------------------

### Start manual wizard

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/AI_ENDPOINT_WIZARD.md

Starts the interactive wizard and selects manual mode. The wizard prompts for mode selection.

```bash
flapii endpoints wizard
# Choose: "Manual (step-by-step)"
```

--------------------------------

### Install flapi-io from PyPI

Source: https://github.com/datazoode/flapi/blob/main/AGENTS.md

Installs the flapi-io package, which provides both the flapi server and the flapii CLI. The package name on PyPI is flapi-io because 'flapi' was taken.

```bash
pip install flapi-io    # installs both `flapi` (server) and `flapii` (CLI)
```

--------------------------------

### Install dependencies with uv

Source: https://github.com/datazoode/flapi/blob/main/test/integration/README.md

Install the project and its dependencies in editable mode using uv pip.

```bash
uv pip install -e .
```

--------------------------------

### Host Override Examples

Source: https://github.com/datazoode/flapi/blob/main/docs/CLI_REFERENCE.md

Examples of overriding the bind host via CLI flag and environment variable.

```bash
# Loopback only (useful behind a reverse proxy)
./flapi --host 127.0.0.1

# 12-factor: pick up the host from the environment
export FLAPI_HOST=127.0.0.1
./flapi
```

--------------------------------

### Complex Example

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Combines includes, environment variables, and conditional logic in a single endpoint configuration.

```yaml
# Main endpoint configuration
url-path: /analytics/{{env.API_VERSION}}/customers

# Conditional authentication
{{include:auth from common/{{env.AUTH_TYPE}}-auth.yaml if env.ENABLE_AUTH}}

# Environment-specific request validation
{{include:request from common/{{env.ENVIRONMENT}}-validation.yaml}}

# Shared components
{{include:rate-limit from common/rate-limit.yaml}}
{{include:cache from common/{{env.CACHE_STRATEGY}}-cache.yaml}}

template-source: analytics/customers-{{env.ENVIRONMENT}}.sql
connection: 
  - {{env.PRIMARY_CONNECTION}}
  - {{env.BACKUP_CONNECTION}}
```

--------------------------------

### Example Write Endpoint YAML

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Example write endpoint configuration for POST /customers. Uses operation type write, returns-data true, transaction true, validate-before-write true. Parameters are in body. References insert-customer.sql and customer-db connection.

```yaml
url-path: /customers
method: POST

operation:
  type: write
  returns-data: true           # Include data from RETURNING clause in response
  transaction: true             # Wrap in transaction (default)
  validate-before-write: true   # Stricter validation (default)

request:
  - field-name: name
    field-in: body              # Body parameters for write operations
    description: Customer name
    required: true
    validators:
      - type: string
        min: 1
        max: 255
  - field-name: email
    field-in: body
    description: Customer email
    required: true
    validators:
      - type: email

template-source: insert-customer.sql
connection: [customer-db]
```

--------------------------------

### Health endpoint responses for ready/starting/degraded

Source: https://github.com/datazoode/flapi/blob/main/docs/plans/114-readiness-during-warmup.md

Three example responses from GET /health: 200 when ready, 503 while starting with pending caches, and 503 when degraded with a failed cache. The starting response includes pending cache names; the degraded response includes the failed table and error.

```text
200 {"status":"ready",   "caches":{"total":4,"ready":4,"failed":0},"uptime_s":31}
```

```text
503 {"status":"starting","caches":{"total":4,"ready":1,"failed":0},"uptime_s":7,
     "pending":["norm_product_part","norm_part_frag","norm_locale"]}
```

```text
503 {"status":"degraded","caches":{"total":4,"ready":3,"failed":1},
     "failed":[{"table":"norm_part_frag","error":"..."}]}
```

--------------------------------

### Initialize project and run server (detailed walkthrough)

Source: https://github.com/datazoode/flapi/blob/main/AGENTS.md

Step-by-step: initialize a project, edit `flapi.yaml` for database connections, create endpoint YAML and SQL templates, then run the server with `./flapi -c`.

```bash
flapii project init my-first-api
Setting up flapi project: my-first-api
✅ Created directories
✅ Created flapi.yaml
✅ Created sample endpoint
✅ Created .gitignore
✅ Created reusable configs
✓ Configuration is valid
```

```yaml
connections:
  my-database:
    properties:
      host: localhost
      port: 5432
      user: $DB_USER
      password: $DB_PASSWORD
```

```bash
./flapi -c my-first-api/flapi.yaml
```

--------------------------------

### Path Resolution - Directory Structure and Path Examples

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Shows the directory structure and example include paths for relative path resolution. Paths are resolved relative to the file containing the include directive.

```text
flapi.yaml
├── endpoints/
│   ├── customers.yaml
│   └── orders.yaml
├── common/
│   ├── auth.yaml
│   └── database.yaml
└── config/
    ├── dev.yaml
    └── prod.yaml
```

```yaml
# From endpoints/customers.yaml
{{include from ../common/auth.yaml}}        # Go up one level, then to common/
{{include from ../config/dev.yaml}}        # Go up one level, then to config/
{{include from ./local-overrides.yaml}}    # Same directory as customers.yaml

# From flapi.yaml (root)
{{include from common/auth.yaml}}           # Direct path to common/
{{include from endpoints/shared.yaml}}     # Direct path to endpoints/
```

--------------------------------

### Section Include - Syntax and Example

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Covers the section include directive. The example shows endpoint.yaml including specific sections (request and auth) from two files, with the resulting merged YAML. Only the named sections are included; other sections are ignored.

```yaml
{{include:section_name from file_path}}
```

```yaml
# endpoint.yaml
url-path: /customers
{{include:request from common/customer-fields.yaml}}
{{include:auth from common/security-config.yaml}}
template-source: customers.sql

# common/customer-fields.yaml
request:
  - field-name: customer_id
    field-in: query
    description: Customer ID
    validators:
      - type: int
        min: 1

other_section:
  not_included: true

# common/security-config.yaml
auth:
  enabled: true
  type: basic
  users:
    - username: api_user
      password: secure_password

rate_limit:
  enabled: true
  max: 100
```

```yaml
url-path: /customers
request:
  - field-name: customer_id
    field-in: query
    description: Customer ID
    validators:
      - type: int
        min: 1
auth:
  enabled: true
  type: basic
  users:
    - username: api_user
      password: secure_password
template-source: customers.sql
```

--------------------------------

### Get SQL Template Response

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/CONFIG_SERVICE_API.md

Example response for the get SQL template endpoint.

```text
SELECT * FROM customers
WHERE id = {{params.id}}
{{#params.limit}}
LIMIT {{params.limit}}
{{/params.limit}}
```

--------------------------------

### Initialize a new flapi project (quick start)

Source: https://github.com/datazoode/flapi/blob/main/AGENTS.md

Use the `flapii project init` command to scaffold a new flapi project. The `--force` flag overwrites existing files.

```bash
# Initialize in current directory
flapii project init

# Create new project directory
flapii project init my-api-project

# Force overwrite existing files
flapii project init my-api --force
```

--------------------------------

### Environment Variable Usage Examples

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Shows how to use environment variables in string values, connection properties, file paths, and include paths.

```yaml
# In any string value
database_url: '{{env.DATABASE_URL}}'
password: '{{env.DB_PASSWORD}}'
api_key: '{{env.API_KEY}}'

# In connection properties
connections:
  my-db:
    properties:
      host: '{{env.DB_HOST}}'
      port: '{{env.DB_PORT}}'
      user: '{{env.DB_USER}}'
      password: '{{env.DB_PASSWORD}}'

# In file paths
template-source: 'queries-{{env.ENVIRONMENT}}.sql'

# In include paths
{{include from config/{{env.ENVIRONMENT}}-settings.yaml}}
```

--------------------------------

### Documented endpoint configuration with caching

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Example of a fully documented endpoint with request validation, connection, and caching.

```yaml
# Customer data endpoint
# Provides access to customer information with optional filtering
url-path: /customers

request:
  - field-name: segment
    field-in: query
    description: Filter customers by segment (premium, standard, basic)
    required: false
    validators:
      - type: enum
        allowedValues: [premium, standard, basic]

# Use customer data connection (Parquet files)
connection: [customer-data]

# Cache results for 30 minutes to improve performance
cache:
  enabled: true
  cache-table-name: customers_cache
  refresh-time: 30m
```

--------------------------------

### Get Endpoint Parameters Response

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/CONFIG_SERVICE_API.md

Example JSON response for the get parameters endpoint.

```json
{
  "parameters": [
    {
      "name": "id",
      "in": "query",
      "required": false,
      "default": "1",
      "description": "Customer ID"
    }
  ]
}
```

--------------------------------

### Get Cache Configuration Response

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/CONFIG_SERVICE_API.md

Example JSON response for the get cache configuration endpoint.

```json
{
  "enabled": true,
  "ttl": "5m",
  "template-file": "/path/to/cache-key.sql"
}
```

--------------------------------

### Nested Includes Example

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Demonstrates nested includes where an included file can contain its own include directives, including dynamic paths using `{{env.VAR}}` and relative paths.

```yaml
# main.yaml
{{include from config/base.yaml}}

# config/base.yaml
project_name: my-project
{{include from database/{{env.DB_TYPE}}.yaml}}
{{include from auth/{{env.AUTH_TYPE}}.yaml}}

# database/postgres.yaml
connections:
  main:
    {{include from ../connection-templates/postgres-template.yaml}}

# connection-templates/postgres-template.yaml
init: |
  INSTALL postgres_scanner;
  LOAD postgres_scanner;
properties:
  host: '{{env.POSTGRES_HOST}}'
  database: '{{env.POSTGRES_DB}}'
```

--------------------------------

### File Include

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Includes entire YAML files using the {{include from ...}} syntax. The example shows including common/auth.yaml and common/rate-limit.yaml before defining the endpoint.

```yaml
# Include entire file
{{include from common/auth.yaml}}
{{include from common/rate-limit.yaml}}

url-path: /customers
template-source: customers.sql
```

--------------------------------

### Example description: GET endpoint

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/AI_ENDPOINT_WIZARD.md

A concise natural language description for a GET endpoint with filtering and caching.

```text
Create a GET endpoint for the customers table.
Include parameters for filtering by industry and region.
Cache for 1 hour.
```

--------------------------------

### Build and View CLI Help

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/CLI_LOG_LEVEL_COMPLETE.md

Use these commands to build the CLI and display help for the log-level command. This is the recommended way to start using the CLI after building.

```bash
cd cli
npm run build
node dist/index.js config log-level --help
```

--------------------------------

### Section Include

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Includes specific sections from YAML files using the {{include:section from ...}} syntax. The example includes the 'request' and 'auth' sections.

```yaml
# Include specific sections
url-path: /customers
{{include:request from common/customer-request.yaml}}
{{include:auth from common/basic-auth.yaml}}
template-source: customers.sql
```

--------------------------------

### Get Endpoint by Slug Examples

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/CONFIG_SERVICE_API.md

Example requests for REST and MCP endpoints using the slug convention.

```bash
# REST endpoint
GET /api/v1/_config/endpoints/customers-slash

# MCP tool
GET /api/v1/_config/endpoints/customer_lookup
```

--------------------------------

### Startup order with socket before warmup

Source: https://github.com/datazoode/flapi/blob/main/docs/plans/114-readiness-during-warmup.md

Shows the new startup sequence: initialize database, create API server, start server thread (socket opens), start warmup thread, join server thread. Warmup runs asynchronously via warmUpCachesAsync().

```text
initializeDatabase()          // NO warmup inside; connections/extensions only
create APIServer
start unified_server_thread   // socket opens here, immediately
start warmup thread           // CacheManager::warmUpCachesAsync()
join server thread
```

--------------------------------

### flapi.yaml: Environment-aware API configuration

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Main configuration file that includes environment-specific connection and settings files using template syntax. It sets the database path and threads/max_memory from environment variables, and whitelists environment variables starting with FLAPI_ and ENV_.

```yaml
# flapi.yaml
project_name: multi-env-api
project_description: Environment-aware API configuration

template:
  path: './endpoints'
  environment-whitelist:
    - '^FLAPI_.*'
    - '^ENV_.*'

# Environment-specific includes
{{include from config/{{env.ENVIRONMENT}}-connections.yaml}}
{{include from config/{{env.ENVIRONMENT}}-settings.yaml}}

duckdb:
  db_path: ./{{env.ENVIRONMENT}}_cache.db
  threads: '{{env.FLAPI_THREADS}}'
  max_memory: '{{env.FLAPI_MAX_MEMORY}}'
```

--------------------------------

### Variable Substitution in Included File Content

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Shows environment variable substitution inside the content of included files. The example file config/production-database.yaml uses {{env.VAR}} placeholders for host, password, and database.

```yaml
# config/production-database.yaml
connections:
  prod-db:
    properties:
      host: '{{env.DB_HOST}}'
      password: '{{env.DB_PASSWORD}}'
      database: '{{env.DB_NAME}}'
```

--------------------------------

### Environment Variable Evaluation Examples

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Shows which environment variable values cause the include to be processed. Non-empty values like `1`, `true`, and `yes` include the file; empty, `false`, or unset variables skip it.

```bash
# These will include the file
export ENABLE_AUTH=1
export ENABLE_AUTH=true  
export ENABLE_AUTH=yes

# These will NOT include the file
export ENABLE_AUTH=
export ENABLE_AUTH=false
unset ENABLE_AUTH
```

--------------------------------

### GET /api/v1/_config/environment-variables Response (200)

Source: https://github.com/datazoode/flapi/blob/main/docs/CONFIG_SERVICE_API_REFERENCE.md

Example response listing environment variables with their values and availability status.

```json
{
  "variables": [
    {
      "name": "DB_PASSWORD",
      "value": "***",
      "available": true
    },
    {
      "name": "API_KEY",
      "value": null,
      "available": false
    }
  ]
}
```

--------------------------------

### REST Endpoint Configuration

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Defines a REST endpoint with url-path, method, and pagination options. The url-path is required, method defaults to GET, and with-pagination defaults to true.

```yaml
url-path: string                # Required. API endpoint path (e.g., "/customers")
method: string                  # Optional. HTTP method (default: "GET")
with-pagination: boolean        # Optional. Enable pagination (default: true)
```

--------------------------------

### Header Parameter Example (JSON)

Source: https://github.com/datazoode/flapi/blob/main/FLAPI_AGENT.md

Shows the JSON representation of a header parameter for a GET request to /customers with a custom header X-Custom-Header.

```json
{
  "X-Custom-Header": "value"
}
```

--------------------------------

### GET template - JSON response

Source: https://github.com/datazoode/flapi/blob/main/docs/CONFIG_SERVICE_API_REFERENCE.md

Example 200 response containing the template content. The template includes Mustache placeholders for parameters.

```json
{
  "template": "SELECT * FROM customers\nWHERE 1=1\n{{#params.id}}\n  AND id = {{ params.id }}\n{{/params.id}}"
}
```

--------------------------------

### Response Format JSON

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Example JSON response for a write operation. Contains rows_affected and data array with inserted customer record.

```json
{
  "rows_affected": 1,
  "data": [
    {
      "customer_id": 123,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

--------------------------------

### GET /api/v1/_config/project Response (200)

Source: https://github.com/datazoode/flapi/blob/main/docs/CONFIG_SERVICE_API_REFERENCE.md

Example response containing project configuration fields such as project-name, server-name, http-port, and template path.

```json
{
  "project-name": "my-api",
  "project-description": "Customer data API",
  "server-name": "localhost",
  "http-port": 8080,
  "template": {
    "path": "./sqls"
  }
}
```

--------------------------------

### Quick Start Commands

Source: https://github.com/datazoode/flapi/blob/main/docs/CLI_REFERENCE.md

Basic flAPI startup commands: default config, custom config, custom port, and config validation.

```bash
# Start with default configuration (flapi.yaml in current directory)
./flapi

# Start with custom configuration file
./flapi -c /path/to/config.yaml

# Start on a specific port
./flapi -p 9000

# Validate configuration without starting server
./flapi --validate-config
```

--------------------------------

### Azure Configuration and Start Command

Source: https://github.com/datazoode/flapi/blob/main/docs/features/vfs-cloud-storage.md

Configure Azure Blob Storage using either a connection string or account name and key, then start flAPI with an Azure-hosted config using the az:// URL scheme.

```bash
# Option 1: Connection string
export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=..."

# Option 2: Account name + key
export AZURE_STORAGE_ACCOUNT="mystorageaccount"
export AZURE_STORAGE_KEY="base64key=="

# Start flAPI with Azure-hosted config
./flapi -c az://my-container/path/to/flapi.yaml
```

--------------------------------

### Path Parameter Example (JSON)

Source: https://github.com/datazoode/flapi/blob/main/FLAPI_AGENT.md

Shows the JSON representation of a path parameter for a GET request to /customers/123, where the id is part of the URL path.

```json
{
  "id": "123"
}
```

--------------------------------

### REST Endpoint Configuration

Source: https://github.com/datazoode/flapi/blob/main/docs/bak/config.md

Basic REST endpoint configuration with request validation, pagination, rate limiting, authentication, and caching. The method defaults to GET if not specified.

```yaml
# Basic REST endpoint
url-path: /customers
method: GET  # Optional, defaults to GET

request:
  - field-name: customer_id
    field-in: query
    description: Unique customer identifier
    required: true
    validators:
      - type: int
        min: 1
        max: 999999

template-source: customers.sql
connection: [customer-data]

# Optional features
with-pagination: true
rate-limit:
  enabled: true
  max: 100
  interval: 60

auth:
  enabled: true
  type: basic
  users:
    - username: api_user
      password: secure_password
      roles: [read]

cache:
  enabled: true
  cache-table-name: customers_cache
  cache-source: customers_cache.sql
  refresh-time: 1h
```