Nova Api Laravel Package

Technical Evaluation

Architecture fit. opscale-co/nova-api is a thin HTTP adapter over Laravel Nova's resource metadata. It registers a service provider, reads your existing app/Nova/* resource classes, and exposes them as index/show/store/update/destroy endpoints, reusing Nova fields for serialization and Nova policies for authorization. That is a strong fit for the common case: a Laravel monolith or modular monolith where Nova is the operational back office and the entities you want to expose already have a Nova resource. The architectural bet is that the admin panel definition is the API contract — one place to maintain fields, filters, and permissions. That bet is also the primary risk: the API's shape is derived from UI-oriented metadata, so response payloads, relationship expansion, and field resolution semantics are inherited from Nova rather than designed for API consumers.

Integration feasibility. Mechanically low-effort: composer require, publish the config, set a route prefix and per-resource exposure flags, wire the token middleware, ship. Realistic first-endpoint estimate is days, not weeks, assuming the token model matches your existing auth stack. The gating factor is not effort but evidence: 0 stars, 0 dependents, and documentation that is a one-paragraph description plus a changelog. You would be among the first production adopters, which means the integration work includes reading the source to answer questions the README does not.

Technical risk. Several, in rough order of severity:

• Contract instability via Nova coupling. The package reaches into Nova internals (resource classes, field types, filters, resolveUsing/computed fields). A Nova major upgrade can silently reshape your external API surface with no versioning boundary between them. There is no API version in the URL, so "v1" of your API is effectively "whatever Nova 4/5 currently does."
• Dependency chain. v1.3.0 is a single-line bump to opscale-co/actions ^4.0, categorized as a feature, with no migration notes or compatibility matrix. For a package in the request path, that is a maintenance-discipline signal worth pricing in. It also confirms the surface extends beyond CRUD into Nova action invocation — which raises the audit and idempotency bar considerably.
• Authorization fidelity. Nova policies are resource-level; field-level visibility (canSee, canSeeWhen) is a UI construct. Whether those gates are enforced during serialization is the single most important thing to verify, because the failure mode is silent field leakage to a partner.
• Auth and throttling are bring-your-own. Token auth with configurable middleware is the stated model; there is no indication of rate limiting, token lifecycle, or scope granularity. Those become your build work.
• Low community signal. 0 stars/dependents means no battle-testing, no Stack Overflow corpus, and a likely single-maintainer bus factor.

Key questions for the spike.

1. What are the actual composer.json constraints — Nova 4 vs. 5, Laravel 10/11/12, PHP floor?
2. Are field-level visibility rules enforced on serialization, or only resource-level policies?
3. What is the response envelope, and how much can we reshape it without forking?
4. How are actions invoked — sync or queued — and is there a hook for audit logging and idempotency keys?
5. Does the package ship a token model/table, or delegate to Sanctum/Passport?
6. Is there any throttling, and does it compose with Laravel's throttle middleware?
7. What exactly changed in opscale-co/actions 4.0, and is the release process automated semantic-release?

Integration Approach

Stack fit. Only viable if Nova is deployed and is the system of record for the target entities. It presumes a conventional Laravel app with routes/api.php or equivalent, standard middleware groups, and an auth stack the token middleware can plug into. It does not fit a headless/decoupled architecture, a Nova-being-retired roadmap, or any service that needs a contract owned independently of the admin panel.

Migration path. There is no data migration; this is additive surface area. If bespoke API controllers already exist for the same entities, run the package in parallel behind a distinct prefix, shadow-compare payloads and authorization decisions against the incumbent for a defined window, then retire the hand-written controllers per resource. Do not cut over wholesale.

Compatibility. Three axes to pin before writing code: Nova major version, Laravel major version, and the transitive opscale-co/actions constraint. Also audit middleware collisions — the package's configurable middleware stack must not double-apply session/CSRF or conflict with existing throttle/auth groups — and route-prefix collisions with the existing api.php.

Sequencing.

1. Timeboxed spike (3–5 days). Answer the key questions above against a staging branch. Exit criteria: one resource served read-only, field-level auth verified by test, payload reviewed by the consuming team.
2. Pilot. One low-sensitivity, read-mostly resource. Token issuance, throttle config, audit logging, and error-envelope conventions defined here and reused thereafter.
3. Hardening. Rate limiting, token rotation/revocation, response shaping where needed, and a documented list of exposed resources kept under config review.
4. Action surface. Expand into Nova action invocation only after audit logging and idempotency are settled — this is the highest-blast-radius capability.
5. Consumer onboarding. One credentialed partner or internal service, with an explicit written statement that the contract tracks Nova and is not independently versioned.
6. Lockfile discipline. Pin exact versions; treat every nova-api and opscale-co/actions bump as a regression-test event, not a routine update.

Operational Impact

Maintenance. Assume you will eventually fork or vendor this. A 0-star, single-maintainer package sitting in your request path should be pinned to exact versions, tracked against your Nova upgrade cadence, and have a named internal owner. The realistic maintenance burden is not patching the package but re-validating your external contract every time Nova moves.

Support. Self-support. No community, no issue corpus, no vendor SLA. Budget engineering time to read the source rather than search for answers, and designate one engineer as the internal authority.

Scaling. The package inherits Nova's Eloquent query patterns. Expect N+1 behavior on relationship fields unless eager loading is explicit, and expect index endpoints to be DB-bound. There is no caching layer and no evidence of query-cost controls beyond pagination — cap page size in config and enforce it in middleware. This is appropriate for hundreds to low thousands of requests per minute against a well-indexed database, not for consumer-scale or latency-sensitive traffic.

Failure modes to design against.

• Silent field leakage after a Nova field change or policy edit — mitigate with contract tests asserting the serialized field set per resource.
• Breaking serialization after a Nova or package upgrade — mitigate with the same contract tests plus a staging environment that mirrors production Nova config.
• Auth bypass via misconfiguration — a resource exposed in config without a corresponding policy, or middleware accidentally loosened, is an open endpoint. Enforce an allowlist and test each exposure.
• Policy/validation divergence — Nova form validation is not API request validation; store/update may accept shapes the admin UI would reject, or vice versa.
• Unaudited action invocation — no action fires without a log record and an idempotency key.
• Transitive major bump breaking action endpoints — the opscale-co/actions ^4.0 move is exactly this class of event.

Ramp-up. Low. Any Laravel-fluent engineer can be productive in a day; the learning curve is Nova's metadata model, not the package. The organizational ramp-up is the harder part: getting product and partner-facing stakeholders to accept that the external API's shape is governed by an internal admin UI, and that changes to Nova resources are therefore changes to a published interface.