Skip to main content

Parameters

Parameters allow clients to customize API requests. flAPI supports query parameters, path parameters, headers, and request bodiesβ€”all with built-in validation and documentation.

Parameter Sources​

Parameters can come from four locations:

Query Parameters​

Most common parameter type for filtering and search.

Basic Configuration​

# Endpoint: /customers?segment=AUTO&active=true
url-path: /customers/
request:
- field-name: segment
field-in: query
description: Market segment to filter by
required: false

- field-name: active
field-in: query
description: Filter by active status
required: false

Usage in SQL​

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

API Calls​

# All customers
curl http://localhost:8080/customers/

# Filtered by segment
curl http://localhost:8080/customers/?segment=AUTO

# Multiple filters
curl http://localhost:8080/customers/?segment=AUTO&active=true

Path Parameters​

Used for resource identification in the URL.

Configuration​

# Endpoint: /customers/{id}/
url-path: /customers/{id}/
request:
- field-name: id
field-in: path
description: Customer ID
required: true # Path parameters are always required
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}}}

API Call​

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

Multiple Path Parameters​

# /orders/{order_id}/items/{item_id}/
url-path: /orders/{order_id}/items/{item_id}/
request:
- field-name: order_id
field-in: path
required: true
- field-name: item_id
field-in: path
required: true

Header Parameters​

For authentication, metadata, and context.

Configuration​

request:
- field-name: api_key
field-in: header
description: API authentication key
required: true

- field-name: x_user_region
field-in: header
description: User's region for data filtering
required: false

API Call​

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

Common Use Cases​

Authentication:

- field-name: authorization
field-in: header
description: Bearer token
required: true

User Context:

- field-name: x_user_id
field-in: header
description: Current user ID for row-level security
required: true

Request Metadata:

- field-name: x_request_id
field-in: header
description: Request tracing ID
required: false

Body Parameters (POST/PUT)​

For data submission in POST and PUT requests.

Configuration​

url-path: /customers/
methods: ['POST']
request:
- field-name: customer_data
field-in: body
description: Customer information to create
required: true
validators:
- type: object
schema:
name:
type: string
required: true
email:
type: string
required: true
segment:
type: string
enum: ['AUTOMOTIVE', 'BUILDING', 'FURNITURE']

API Call​

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

SQL Template​

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

Parameter Configuration​

Required vs Optional​

# Required parameter (must be provided)
- field-name: customer_id
field-in: query
required: true
validators:
- type: int

# Optional parameter (can be omitted)
- field-name: segment
field-in: query
required: false

Default Values​

Provide defaults in SQL template:

-- Default limit to 100 if not provided
SELECT * FROM products
LIMIT {{{params.limit|100}}}
OFFSET {{{params.offset|0}}}

Descriptions​

Always document parameters:

- field-name: date_from
field-in: query
description: Start date for filtering (format: YYYY-MM-DD). Defaults to 30 days ago.
required: false

Common Parameter Patterns​

Pagination​

request:
- field-name: limit
field-in: query
description: Number of records to return (max 100)
required: false
validators:
- type: int
min: 1
max: 100

- field-name: offset
field-in: query
description: Number of records to skip
required: false
validators:
- type: int
min: 0
SELECT * FROM products
LIMIT {{{params.limit|20}}}
OFFSET {{{params.offset|0}}}
request:
- field-name: search
field-in: query
description: Search term for product name or description
required: false
validators:
- type: string
min_length: 3
max_length: 100
SELECT * FROM products
WHERE 1=1
{{#params.search}}
AND (
product_name ILIKE '%{{{params.search}}}%'
OR description ILIKE '%{{{params.search}}}%'
)
{{/params.search}}

Sorting​

request:
- field-name: sort_by
field-in: query
description: Field to sort by
required: false
validators:
- type: string
enum: ['name', 'price', 'created_at', 'popularity']

- field-name: sort_order
field-in: query
description: Sort direction
required: false
validators:
- type: string
enum: ['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}}
{{{params.sort_order}}}
{{/params.sort_order}}
{{^params.sort_order}}
DESC
{{/params.sort_order}}

Date Ranges​

request:
- field-name: start_date
field-in: query
description: Start date (YYYY-MM-DD)
required: false
validators:
- type: string
pattern: '^\d{4}-\d{2}-\d{2}$'

- field-name: end_date
field-in: query
description: End date (YYYY-MM-DD)
required: false
validators:
- type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
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}}

Multi-Select Filters​

request:
- field-name: categories
field-in: query
description: Comma-separated list of categories
required: false
SELECT * FROM products
WHERE 1=1
{{#params.categories}}
AND category IN (
{{#split params.categories ','}}
'{{{.}}}'{{^-last}},{{/-last}}
{{/split}}
)
{{/params.categories}}

Accessing Parameters in SQL​

Basic Access​

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

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

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

Conditional Blocks​

-- Include block only if parameter exists
{{#params.status}}
AND status = '{{{params.status}}}'
{{/params.status}}

-- Include block if parameter does NOT exist
{{^params.include_inactive}}
AND active = true
{{/params.include_inactive}}

Nested Access​

-- Body parameter: {"filter": {"segment": "AUTO"}}
WHERE segment = '{{{params.filter.segment}}}'

Testing Parameters​

Validate Configuration​

$ flapii endpoints validate /customers/

βœ“ Parameters configured correctly
β€’ segment (query, optional, string enum)
β€’ id (query, optional, int min:1)
β€’ active (query, optional, boolean)

Test Template Expansion​

$ flapii templates expand /customers/ \
--params '{"segment": "AUTO", "active": true}'

Expanded SQL:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SELECT * FROM customers
WHERE 1=1
AND market_segment = 'AUTO'
AND active = true
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Test API Call​

$ curl -v "http://localhost:8080/customers/?segment=AUTO&active=true"

< HTTP/1.1 200 OK
< Content-Type: application/json
{
"data": [...]
}

Best Practices​

1. Always Validate Parameters​

# βœ… Good: Validated enum
validators:
- type: string
enum: ['active', 'inactive', 'pending']

# ❌ Bad: No validation (SQL injection risk)

2. Use Descriptive Names​

# βœ… Good
field-name: customer_segment
field-name: order_status
field-name: min_price

# ❌ Bad
field-name: s
field-name: st
field-name: p

3. Document Thoroughly​

- field-name: date_from
field-in: query
description: |
Start date for filtering orders (ISO 8601 format: YYYY-MM-DD).
Defaults to 30 days ago if not provided.
Example: 2024-01-01
required: false

4. Set Reasonable Limits​

validators:
- type: int
min: 1
max: 100 # Prevent excessive data requests

- type: string
max_length: 100 # Prevent long search strings

5. Use Consistent Naming​

# βœ… Good: Consistent snake_case
field-name: customer_id
field-name: order_date
field-name: product_category

# ❌ Bad: Mixed styles
field-name: customerId
field-name: order-date
field-name: ProductCategory

6. Provide Examples in OpenAPI​

Parameters are automatically documented in OpenAPI with examples:

- field-name: segment
description: Market segment (e.g., AUTOMOTIVE)
example: AUTOMOTIVE

Common Issues​

Missing Required Parameter​

Error: 400 Bad Request
{
"error": "Missing required parameter: customer_id"
}

Fix: Provide the required parameter in your request.

Invalid Parameter Value​

Error: 400 Bad Request
{
"error": "Parameter 'status' must be one of: active, inactive"
}

Fix: Use a valid enum value.

Parameter Not Accessible in SQL​

-- ❌ Wrong: Missing params prefix
WHERE customer_id = {{{customer_id}}}

-- βœ… Correct: With params prefix
WHERE customer_id = {{{params.customer_id}}}

Next Steps​

πŸͺ Cookie Settings