Declarative APIs Reference

FW uses yaml definitions in the api/ directory to strictly define the API contract. The CLI command fw build:api compiles these into Route definitions, strict DTOs, and base Handlers.

The YAML Structure

A typical file looks like api/user.yaml:

apiVersion: fw/v1
entity: User

# Endpoints array
endpoints:
  - method: GET
    path: /users
    action: paginate
    response: JsonResponse

  - method: POST
    path: /users
    action: create
    payload: CreateUserDto
    response: JsonResponse

Top-Level Nodes

• apiVersion: Reserved for future versioning (currently fw/v1).
• entity: The module domain. Determines the namespace. E.g., User means the generated handler will be Modules\User\CreateUserHandler.
• endpoints: An array of route definitions.

Endpoint Nodes

• method: The HTTP verb (GET, POST, PUT, PATCH, DELETE).
• path: The relative URI. Path parameters are enclosed in braces: /users/{id}.
• action: The logical action name. Combines with entity to create the Handler class name.
  • e.g., action create on entity User -> CreateUserHandler.
  • FW provides scaffolding shortcuts: action: crud will auto-generate 5 endpoints (paginate, get, create, update, delete).
• payload: The name of the incoming DTO. (e.g., CreateUserDto).
• response: The type of Response object. Currently defaults to JsonResponse. FW is designed as an API-First backend, so most endpoints return JSON. Future implementations will support HtmlResponse for compiled views.
• partial (optional): Set to true to skip scaffolding the PHP Handler class. FW will compile the route, but leave the implementation file up to you.
• approval (optional): Set to true to require Human-in-the-loop approval. The request will be blocked with a 403 status by the HumanInTheLoopMiddleware unless explicitly approved.

Payload Validation

FW's compiler reads strict constraints off the DTO properties in the YAML and automatically enforces them. If validation fails, FW intercepts the request before it hits your Handler, returning a unified 422 Unprocessable Entity JSON response and preventing your application logic from dealing with bad data.

Defining Constraints

Define your endpoint's payload inline within your module's api/*.yaml (e.g., api/user.yaml):

# ... endpoints definition ...
  - method: POST
    path: /users
    action: create
    payload: CreateUserDto
    response: JsonResponse

# DTO Definitions
dtos:
  CreateUserDto:
    email: string @required @email @max(255)
    age: int @min(18) @max(120)
    password: string @required @min(8) @regex(/^[A-Za-z0-9]+$/)
    username: string? @alpha_dash

Supported Validation Tokens

FW compiles the following tokens into a raw validation sequence native to PHP:

• @required: The property cannot be null or omitted.
• @email: Must be a valid email format.
• @min(value): For strings, minimum length. For integers, minimum numeric value.
• @max(value): For strings, maximum length. For integers, maximum numeric value.
• @regex(/pattern/): Must match the provided regex.
• @alpha_dash: Alpha-numeric characters, strings, and dashes only.

When the CLI sees @email on an email: string type, it compiles an if (!filter_var($payload['email'], FILTER_VALIDATE_EMAIL)) check directly into your routing pipeline.