Api Laravel Package

Getting Started

SeviaFlow API is a thin REST/OpenAPI layer over SeviaFlow Core. It does not define resources itself — it reflects whatever resources and capabilities your Core installation exposes. That ordering matters for your first hour with the package:

1. Install the adapter alongside Core:

   composer require seviaflow/api:^0.1@beta
   

2. Confirm your baseline is a verified target (Laravel 12 / PHP 8.2+ or Laravel 13 / PHP 8.3+). On Laravel 11 or PostgreSQL you are outside the beta support matrix — expect to debug, and pin exact versions.
3. Authenticate before you curl. The package uses Laravel's guard system with Sanctum as the default. Make sure Sanctum is installed, the HasApiTokens trait is on your user model, and you can mint a token before you start hitting endpoints — a 401 on your first request is almost always Sanctum wiring, not the package.
4. Read the package docs at the version you installed (https://seviaflow.io/docs/0.1/api/) rather than latest. Beta docs and beta code drift together.
5. Enable a capability on one Core resource, then list your routes (php artisan route:list --path=api). This is the fastest way to see the package's real contract: routes appear because a capability is enabled, not because you wrote them.

First use case: take a single existing Core resource, enable only its read/list capability, and expose it to an internal dashboard or mobile client. That exercises authentication, policy authorization, serialization, and OpenAPI generation in one pass without the blast radius of full CRUD.

Implementation Patterns

Treat capabilities as the source of truth, not routes. Day-to-day, you will not edit route files. You enable or disable a capability on a resource (create, read, update, delete, workflow) and the endpoint set materializes. When a client asks "why doesn't the delete endpoint exist?", the answer lives in resource configuration. This is the single most important mental model for working in this package.

Feature work flows capability → policy → schema. When adding write access to a resource, do it in three deliberate steps: enable the capability, write or update the resource policy so authorization is meaningful, then adjust serialization so the shape the client sees is intentional. Skipping the middle step is how you ship an authenticated-but-wide-open endpoint.

Layer token abilities over policies, don't substitute them. Both gates apply: the token must carry the ability and the policy must permit the action for that record. Use abilities for coarse-grained client scoping (a read-only integration token) and policies for row-level rules (this user may only edit their own records). Plan for both to be exercised in tests.

Customize serialization centrally. Resource serialization is a package responsibility, but you will want to shape output per resource — hide internal fields, embed relations. Keep these definitions alongside your resource configuration so a capability change and its output change land in the same review.

Use workflow endpoints as domain actions, not generic updates. The workflow endpoints exist so state transitions are explicit, auditable API calls rather than a client PATCHing a status column. Model them as named actions in your clients and controllers; it keeps the API surface legible and makes later policy work far easier.

Generate OpenAPI as part of your release process. The generation step is only useful if it runs on every capability or serialization change. Wire it into CI, diff the artifact on pull requests, and generate typed clients from it. Treat the spec as a build output, not a one-time export.

Testing pattern: issue real Sanctum tokens in your test suite and assert both the happy path and the two failure modes — insufficient token ability and policy denial. They should be distinguishable in your tests even if you return the same status code.

Integration tip: the package needs neither the UI package nor Livewire. If you are building an API-only service or a headless backend, you can keep the dependency tree lean. If you already run Core with UI, the API package layers on cleanly without disturbing it.

Gotchas and Tips

• Beta means the contract moves. Pin seviaflow/api to an exact beta version in composer.json and read changelogs before bumping. Route shapes, serialization, and the OpenAPI output are all fair game pre-1.0.
• Unverified ≠ unsupported, but budget for it. Laravel 11 and PostgreSQL have not been validated. If you must run PostgreSQL, get your migrations and JSON/array column behavior under test early; those are typical failure points for ORM-backed API packages.
• A missing endpoint is a configuration bug, not a routing bug. Before touching route caching or providers, confirm the capability is enabled on the resource. php artisan route:list after a config change tells you immediately.
• 401 vs 403 vs 404 is your debugging ladder. 401 is guard/Sanctum configuration; 403 is usually token abilities or the resource policy; 404 on a resource you know exists often means the capability is disabled or the record is not visible under policy. Learn this mapping — it saves hours.
• Guard is configurable, default is Sanctum. If you run multiple guards (e.g. a separate admin guard), verify which one the API routes resolve to. A correctly-formed token on the wrong guard still yields 401.
• No entitlement adapter, no paid gate. The MIT license means there is no license key to trip over — if authorization fails, it is Sanctum or a policy, never licensing. Do not go looking for a licensing bug.
• Regenerate OpenAPI after config changes. The spec reflects capability state at generation time. A stale artifact is a common source of "the docs say this endpoint exists" confusion.
• Extension points to prefer: serialization definitions and resource policies are the intended customization seams. Reaching into package internals will cost you on the next beta bump, since internals are explicitly unstable.
• Keep a smoke test across the beta upgrade. A small suite that lists routes, calls one authenticated read endpoint, and regenerates the spec will catch the majority of beta-to-beta breakage in seconds.