Parameters

Parameters let clients customise API requests. flAPI extracts them from four locations — query, path, header, and body — and exposes them to SQL templates as params.<name>.

Parameter Sources

Each request: entry uses these top-level keys:

Key	Required	Description
`field-name`	yes	Name used in SQL as `params.<field-name>`
`field-in`	yes	`query`, `path`, `header`, or `body`
`description`	no	Human-readable description (also surfaces in OpenAPI)
`required`	no	Default `false`
`default`	no	Default value (always a string in YAML)
`validators`	no	List of validators — see Validation

Query Parameters

The most common type — used for filtering and search.

# GET /customers?segment=AUTOMOBILE&id=42
url-path: /customers/
method: GET

request:
  - field-name: segment
    field-in: query
    description: Market segment to filter by
    required: false
    validators:
      - type: enum
        allowedValues: [AUTOMOBILE, BUILDING, FURNITURE, HOUSEHOLD, MACHINERY]

  - field-name: id
    field-in: query
    description: Customer ID
    required: false
    validators:
      - type: int
        min: 1

Usage in SQL

SELECT * FROM customers
WHERE 1=1
{{#params.segment}}
  AND market_segment = '{{{ params.segment }}}'
{{/params.segment}}
{{#params.id}}
  AND id = {{ params.id }}
{{/params.id}}

Calls

curl http://localhost:8080/customers/
curl 'http://localhost:8080/customers/?segment=AUTOMOBILE'
curl 'http://localhost:8080/customers/?segment=AUTOMOBILE&id=42'

Path Parameters

Used for resource identification. flAPI uses colon-prefixed placeholders in url-path (:id, :customer_uuid, ...).

# /customers/:id
url-path: /customers/:id
method: GET

request:
  - field-name: id
    field-in: path
    description: Customer ID
    required: true
    validators:
      - type: int
        min: 1

SQL Template

SELECT
  c_custkey  AS id,
  c_name     AS name,
  c_acctbal  AS balance
FROM customers
WHERE c_custkey = {{ params.id }}

Call

curl http://localhost:8080/customers/12345

Multiple Path Parameters

url-path: /orders/:order_id/items/:item_id
method: GET

request:
  - field-name: order_id
    field-in: path
    required: true
    validators:
      - type: int
        min: 1

  - field-name: item_id
    field-in: path
    required: true
    validators:
      - type: int
        min: 1

Header Parameters

For authentication, multi-tenancy, and request metadata.

request:
  - field-name: api_key
    field-in: header
    description: API authentication key
    required: true
    validators:
      - type: string
        min: 16
        max: 64
        regex: '^[A-Za-z0-9_-]+$'

  - field-name: x_user_region
    field-in: header
    description: User's region for data filtering
    required: false
    validators:
      - type: enum
        allowedValues: [US, EU, APAC, LATAM]

curl http://localhost:8080/customers/ \
  -H 'X-API-Key: your-api-key' \
  -H 'X-User-Region: US'

Body Parameters (POST/PUT/PATCH)

When method: is POST, PUT, PATCH or DELETE, body fields are declared with field-in: body. Each field is a top-level key in the JSON body — flAPI does not support nested object/array validators; declare each leaf field separately.

url-path: /customers/
method: POST

request:
  - field-name: name
    field-in: body
    required: true
    validators:
      - type: string
        min: 2
        max: 100
        regex: '^[A-Za-z ]+$'

  - field-name: email
    field-in: body
    required: true
    validators:
      - type: email

  - field-name: segment
    field-in: body
    required: true
    validators:
      - type: enum
        allowedValues: [AUTOMOBILE, BUILDING, FURNITURE]

template-source: customers-create.sql
connection: [customers-parquet]

curl -X POST http://localhost:8080/customers/ \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "New Customer",
    "email": "customer@example.com",
    "segment": "AUTOMOBILE"
  }'

SQL Template

INSERT INTO customers (name, email, segment)
VALUES (
  '{{{ params.name }}}',
  '{{{ params.email }}}',
  '{{{ params.segment }}}'
)
RETURNING *

See Write Operations for the full CRUD configuration.

Default Values

default: is always a string in YAML. Validators run after the default is applied, so the default must be valid:

- field-name: status
  field-in: query
  default: "active"
  validators:
    - type: enum
      allowedValues: [active, inactive, pending]

- field-name: limit
  field-in: query
  default: "100"
  validators:
    - type: int
      min: 1
      max: 1000

In SQL templates, you can also fall back via Mustache:

LIMIT {{#params.limit}}{{ params.limit }}{{/params.limit}}{{^params.limit}}100{{/params.limit}}

Common Patterns

Pagination

Pagination is automatic when with-pagination is true (the default). The limit / offset query parameters are always accepted; declare them explicitly only when you want validators on them.

with-pagination: true   # default

request:
  - field-name: limit
    field-in: query
    required: false
    validators:
      - type: int
        min: 1
        max: 1000

  - field-name: offset
    field-in: query
    required: false
    validators:
      - type: int
        min: 0

Search

request:
  - field-name: search
    field-in: query
    required: false
    validators:
      - type: string
        min: 3
        max: 100
        regex: '^[A-Za-z0-9 _-]+$'

SELECT * FROM products
WHERE 1=1
{{#params.search}}
  AND (name ILIKE '%{{{ params.search }}}%' OR description ILIKE '%{{{ params.search }}}%')
{{/params.search}}

Sorting

request:
  - field-name: sort_by
    field-in: query
    required: false
    validators:
      - type: enum
        allowedValues: [name, price, created_at, popularity]

  - field-name: sort_order
    field-in: query
    required: false
    default: "DESC"
    validators:
      - type: enum
        allowedValues: [ASC, DESC]

SELECT * FROM products
ORDER BY {{#params.sort_by}}{{{ params.sort_by }}}{{/params.sort_by}}{{^params.sort_by}}created_at{{/params.sort_by}} {{{ params.sort_order }}}

Date Range

request:
  - field-name: start_date
    field-in: query
    required: false
    validators:
      - type: date
        min: "2000-01-01"

  - field-name: end_date
    field-in: query
    required: false
    validators:
      - type: date

SELECT * FROM orders
WHERE 1=1
{{#params.start_date}}
  AND order_date >= '{{{ params.start_date }}}'
{{/params.start_date}}
{{#params.end_date}}
  AND order_date <= '{{{ params.end_date }}}'
{{/params.end_date}}

Accessing Parameters in SQL

-- Query parameter ?customer_id=123
WHERE customer_id = {{ params.customer_id }}

-- Path parameter /customers/:id
WHERE customer_id = {{ params.id }}

-- Header X-Region: US
WHERE region = '{{{ params.x_region }}}'

-- Body field "name"
INSERT INTO customers (name) VALUES ('{{{ params.name }}}')

Pick the brace form by validator type:

int, date, time (numeric/identifier-like): {{ params.x }} (double).
string, enum, email, uuid (string-like): '{{{ params.x }}}' (triple, quoted).

Conditional Blocks

{{#params.status}}
  AND status = '{{{ params.status }}}'
{{/params.status}}

{{^params.include_inactive}}
  AND active = true
{{/params.include_inactive}}

Best Practices

1. Always validate

validators:
  - type: enum
    allowedValues: [active, inactive]

2. Use snake_case for field names

field-name: customer_id
field-name: order_date
field-name: product_category

3. Document with `description:`

description ends up in the auto-generated OpenAPI doc.

- field-name: date_from
  field-in: query
  description: |
    Start date for filtering orders (YYYY-MM-DD).
    Defaults to 30 days ago if not provided.
  default: "2024-01-01"
  validators:
    - type: date

4. Bound numeric ranges

validators:
  - type: int
    min: 1
    max: 1000

5. Enable strict field validation for sensitive endpoints

request-fields-validation: true   # rejects requests with extra params

Common Issues

Missing required parameter

{
  "errors": [{ "field": "customer_id", "message": "Required field is missing" }]
}

Invalid value

{
  "errors": [{ "field": "status", "message": "Invalid enum value" }]
}

Parameter not visible in SQL

-- Wrong: missing prefix
WHERE customer_id = {{ customer_id }}

-- Correct
WHERE customer_id = {{ params.customer_id }}

Next Steps

Validation — the seven validator types in detail
SQL Templating — Mustache syntax for templates
Endpoints Overview — full endpoint tutorial
Authentication — secure parameter access

Parameter Sources​

Query Parameters​

Usage in SQL​

Calls​

Path Parameters​

SQL Template​

Call​

Multiple Path Parameters​

Header Parameters​

Body Parameters (POST/PUT/PATCH)​

SQL Template​

Default Values​

Common Patterns​

Pagination​

Search​

Sorting​

Date Range​

Accessing Parameters in SQL​

Conditional Blocks​

Best Practices​

1. Always validate​

2. Use snake_case for field names​

3. Document with description:​

4. Bound numeric ranges​

5. Enable strict field validation for sensitive endpoints​

Common Issues​

Missing required parameter​

Invalid value​

Parameter not visible in SQL​

Next Steps​

Parameter Sources

Query Parameters

Usage in SQL

Calls

Path Parameters

SQL Template

Call

Multiple Path Parameters

Header Parameters

Body Parameters (POST/PUT/PATCH)

SQL Template

Default Values

Common Patterns

Pagination

Search

Sorting

Date Range

Accessing Parameters in SQL

Conditional Blocks

Best Practices

1. Always validate

2. Use snake_case for field names

3. Document with `description:`

4. Bound numeric ranges

5. Enable strict field validation for sensitive endpoints

Common Issues

Missing required parameter

Invalid value

Parameter not visible in SQL

Next Steps