API Reference

Complete reference for all Frey APIs, types, and generated routes

API Reference

Complete reference for all Frey APIs and types.

Core Functions

defineEntity<Schema>(entity: Entity<Schema>)

Creates a new entity definition with CRUD operations and custom routes.

Parameters:

  • entity: Entity<Schema> - Entity configuration object

Returns:

  • Entity<Schema> - Configured entity ready for use with startServer

Example:

startServer(fastify: FastifyInstance, options: ServerOptions)

Starts the HTTP server with the provided entities.

Parameters:

  • fastify: FastifyInstance - Fastify server instance
  • options: ServerOptions - Server configuration

Example:

Types

Entity<Schema>

Entity configuration object.

ServerOptions

Server configuration options.

Handler

Handler function type for CRUD operations.

Context

Context object passed to handlers.

CustomRoute

Custom route configuration.

HTTPMethod

Supported HTTP methods.

RouteHandler

Custom route handler function.

Params

Query parameters object.

QueryParams

Extended query parameters.

OrderField

Sort field configuration.

Generated Routes

For each entity, Frey automatically generates the following routes:

GET /{entity}

Lists all entities with optional filtering, sorting, and pagination.

Query Parameters:

  • limit?: number - Number of items to return
  • offset?: number - Number of items to skip
  • sort?: string - Field to sort by
  • order?: 'asc' | 'desc' - Sort direction
  • search?: string - Search term
  • filters?: object - Field-specific filters

Handler: findAll

Example:

POST /{entity}

Creates a new entity.

Request Body: Validated against entity schema

Handler: create

Example:

GET /{entity}/:id

Retrieves a specific entity by ID.

URL Parameters:

  • id - Entity identifier

Handler: findOne

Example:

PUT /{entity}/:id

Updates an existing entity.

URL Parameters:

  • id - Entity identifier

Request Body: Validated against entity schema

Handler: update

Example:

DELETE /{entity}/:id

Deletes an entity.

URL Parameters:

  • id - Entity identifier

Handler: delete

Example:

Error Handling

Frey provides consistent error handling across all endpoints.

Validation Errors

When request data doesn't match the entity schema:

Handler Errors

When handlers throw errors:

Not Found Errors

When entities are not found:

Utility Functions

z (Zod)

Frey re-exports Zod for convenience:

Best Practices

  1. Use TypeScript: Leverage TypeScript for better development experience
  2. Validate schemas: Use Zod schemas for runtime validation
  3. Handle errors: Always handle potential errors in handlers
  4. Use appropriate HTTP methods: Follow REST conventions
  5. Document custom routes: Consider adding OpenAPI documentation
  6. Test thoroughly: Write tests for all handlers and custom routes

Examples

Basic Entity

Entity with Custom Routes

Next Steps