API: Exposing a Resource

Installing seviaflow/api registers API routes, but it does not expose every model. Each Resource must opt in and declare which fields and operations a client may use. This allowlist is separate from authentication and authorization: configure the API middleware and Laravel policies or SeviaFlow permissions as described in Authorization.

Enable API access

Add an api() method to the Resource. This example allows reading a small set of fields, creating and updating selected fields, and deleting records:

use SeviaFlow\Core\Resources\ApiResource;

public static function api(ApiResource $api): ApiResource
{
    return $api
        ->enabled()
        ->readable(['id', 'name', 'email', 'status'])
        ->creatable(['name', 'email', 'status'])
        ->updatable(['name', 'email', 'status'])
        ->requiredOnCreate(['name', 'email'])
        ->useFormFieldRules()
        ->deletable();
}

Use only the fields a client actually needs. For example, omitting password, internal notes, or administrative flags from these lists prevents the API from returning or accepting them through this Resource.

What each setting controls

Method	Effect	Use it when
`enabled()` / `disabled()`	Turns API exposure for this Resource on or off.	Call `enabled()` before declaring an API contract. Use `disabled()` to keep the Resource out of the API.
`readable([...])`	Allow-lists fields returned by index and show requests. This is independent of the columns visible in the UI table.	Include only values the API client is allowed to see.
`creatable([...])`	Allow-lists fields accepted when a client creates a record.	Include fields the client may provide during `POST`.
`updatable([...])`	Allow-lists fields accepted when a client updates a record.	Include fields the client may change during `PATCH`.
`requiredOnCreate([...])`	Requires the listed fields on a create request.	Use for fields that must be present when a new record is made.
`requiredOnUpdate([...])`	Requires the listed fields on an update request.	Use only when an update must contain those fields; ordinary partial updates can omit other fields.
`useFormFieldRules()`	Reuses the Resource form field validation rules for API create/update requests.	Use when the API and UI should enforce the same field rules.
`deletable()`	Enables the API delete operation for this Resource.	Call only when clients should be able to delete records.
`flow()`	Enables the workflow read and transition endpoints for this Resource.	Use when the Resource defines a workflow and clients should execute its named transitions.
`schema([...])`	Declares or overrides API transport schemas used to describe fields in OpenAPI.	Use for headless fields or types, such as UUIDs or money, whose API shape cannot be inferred from a form field.

How the contract maps to requests

GET index and show requests require readable([...]).
POST requires an enabled Resource and configured creatable fields; requiredOnCreate([...]) adds fields that must be present.
PATCH uses the updatable field allowlist and any required update fields.
DELETE is available only when deletable() is enabled.
Workflow transitions use flow() and the transition rules declared by the Resource.

See CRUD and Index Queries for request paths and search parameters, OpenAPI for schema output, and API Installation for authentication setup.

Payload safety

SeviaFlow removes fields outside the configured create or update allowlist before saving. When a workflow owns a state field, the API also guards that field so a client must use an allowed transition instead of changing state directly. An allowlist does not decide which authenticated user may act: policies, role permissions, tenant scoping, and API middleware must still be configured for the application.