Api Laravel Package

Product Decisions This Supports

• API-first / headless delivery. The adapter exposes SeviaFlow Core resources as authenticated REST endpoints without requiring the UI package or Livewire. This makes "headless mode" a viable roadmap item rather than a bespoke engineering project — you can serve a mobile app, SPA, or partner integration from the same resource definitions that power the admin surface.
• Build vs. buy for the API layer. The alternative is hand-rolling controllers, serialization, route registration, and auth for every resource. This package makes that a configuration exercise driven by each resource's capabilities, which is the classic "buy" case: commodity plumbing, low differentiation, high maintenance cost if built in-house.
• OpenAPI as a product artifact. Generated specs unlock SDK generation, contract tests, a developer docs portal, and API versioning discipline. That is a product-facing capability (developer experience, partner onboarding), not just an engineering convenience.
• New commercial surface. If the roadmap includes an "API access" tier, integrations marketplace, or embedded/automation use cases, workflow endpoints let external systems read state and drive transitions programmatically. That is the foundation for webhooks, scheduled automation, and third-party orchestration.
• Security and enterprise review readiness. Sanctum guard plus policy- and token-ability-based authorization means per-integration scoping maps onto the authorization model you already maintain in Core. That shortens security review for prospects who ask "how do you scope a partner's access?"
• Decoupling option value. Because it does not depend on Livewire, it reduces the cost of eventually changing or splitting the presentation layer — a hedge worth noting in architecture decisions even if not acted on this quarter.

When to Consider This Package

Adopt when:

• You are already running SeviaFlow Core and need external access to those same resources. The value is proportional to how much of your domain is already modeled as Core resources; on a greenfield or non-Core app there is nothing to adapt.
• You are on Laravel 12 / PHP 8.2+ or Laravel 13 / PHP 8.3+, the verified beta targets.
• You want an OpenAPI-first contract for external consumers, or need to serve a front end that cannot live inside the UI package.
• You can pin to ^0.1@beta with a committed lockfile and absorb upgrade work when the stable API lands.
• Cost sensitivity favors MIT with no licensing adapter or paid API entitlement — but note that also means community/best-effort support, so plan for internal ownership of upgrades and incident triage.

Look elsewhere or defer when:

• You are on Laravel 11 or PostgreSQL — explicitly unverified. Treat as unsupported until confirmed, not as "probably fine."
• You need a production SLA or stable semver now. This is a first beta; endpoints, serialization shape, and compatibility are stated to change.
• You need GraphQL, field-level or row-level authorization beyond resource policies, multi-tenant isolation not modeled in Core capabilities, or custom non-resource endpoints. Those are extension work, not configuration.
• You require commercial support contracts or vendor-backed security attestations.

How to Pitch It (Stakeholders)

For executives: SeviaFlow API is a free, MIT-licensed adapter that turns the resources we have already modeled into an authenticated public API with a generated OpenAPI spec — the work we would otherwise fund as a multi-week custom build and then maintain indefinitely. It is additive: it does not require the UI package, so nothing we have shipped is at risk. The headline opportunity is reach — mobile, partner, and embed channels can be served without a parallel API codebase. The risk is maturity, not fit: this is a first beta, the API surface will change, and only Laravel 12/13 on PHP 8.2/8.3 with MySQL-family databases is verified. Recommended posture: timeboxed internal pilot behind a locked version pin, targeting one integration, with a go/no-go on stable release rather than a broad rollout on the beta.

For engineering: It is a thin, capability-driven layer over Core — routes are generated from each resource's configured capabilities, authorization flows through existing resource policies and Sanctum token abilities, so there is no second permission model to keep in sync. Workflow endpoints plus serialization and OpenAPI generation are included, so the marginal code we write is integration-specific glue, not request handling. Caveats to design around: beta contract churn, unverified Laravel 11 and PostgreSQL, and no escape hatch for endpoints that do not map to a Core resource. Pin the version, isolate the integration behind our own client boundary, and add contract tests against the generated spec so a beta bump surfaces as a failing test rather than a broken consumer.