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}}}
Searchβ
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β
- Validation: Learn about parameter validation types
- SQL Templating: Master Mustache syntax
- Endpoints Overview: Complete endpoint tutorial
- Authentication: Secure parameter access