Parameter Handling

Frey automatically parses and validates query parameters, request bodies, and URL parameters for your entity endpoints.

Query Parameters

Query parameters are automatically parsed and made available to your handlers through the params object.

Supported Query Parameters

Frey supports several built-in query parameters:

• limit - Number of items to return (pagination)
• offset - Number of items to skip (pagination)
• sort - Field to sort by
• order - Sort direction (asc or desc)
• search - Search term for text fields
• filters - Object with field-specific filters

Basic Usage

Example Requests

URL Parameters

URL parameters (like :id) are automatically extracted and available in handlers:

Request Body

For POST and PUT requests, the request body is automatically validated against your entity schema:

Advanced Parameter Parsing

Custom Parameter Types

You can define custom parameter parsing by extending the built-in types:

Date Range Filtering

Array Parameters

Handle array parameters in query strings:

Validation and Error Handling

Automatic Validation

Frey automatically validates parameters against your Zod schema:

Custom Validation

Add custom validation logic in your handlers:

Parameter Types Reference

Query Parameters

Parameter	Type	Description	Example
limit	number	Items per page	?limit=10
offset	number	Items to skip	?offset=20
sort	string	Sort field	?sort=name
order	'asc' | 'desc'	Sort direction	?order=desc
search	string	Search term	?search=john
filters[field]	any	Field filter	?filters[isActive]=true

URL Parameters

Parameter	Type	Description	Example
id	string	Entity ID	/users/123

Request Body

The request body is validated against your entity schema and passed as the params object.

Best Practices

1. Use built-in parameters: Leverage Frey's built-in parameter parsing when possible
2. Validate early: Let Zod handle basic validation, add business logic validation in handlers
3. Handle errors gracefully: Always handle potential errors in your handlers
4. Document your parameters: Consider documenting custom parameters for API consumers
5. Use appropriate types: Choose the right parameter types for your use case

Common Patterns

Pagination

Search with Highlighting

Complex Filtering

Next Steps

• Learn about Type Safety for better development experience
• Explore Custom Routes for advanced functionality
• Check out Examples for real-world implementations