Json Api Server Laravel Package

Technical Evaluation

Architecture fit

This package is the JSON:API layer for a Laravel application: it sits between the HTTP kernel and Eloquent, owning content negotiation, request validation, serialization, error documents, and OpenAPI schema generation. v1.0.0-rc.1 is not an incremental release — it is a structural refactor of three subsystems (endpoints, query parameter validation, schema generation) plus a rework of the resource ID contract. For a TPM this matters because the package is not a peripheral utility: it defines the external API contract, so its breaking changes are effectively breaking changes to our public API.

Integration feasibility

Feasible, but only with a scheduled migration rather than an opportunistic bump. The breaking changes split into three tiers of effort:

• Mechanical / low ambiguity — helper and namespace removals (json_api_response(), Context::queryParam(), Extension\Atomic, Pagination\Concerns\BuildsUrls), the SingleError → JsonApiError trait rename, and the getJsonApiErrors() → getJsonApiError() signature flip. These surface as hard fatals at boot or dispatch, which is good: they fail loudly and early.
• Structural — Resource::getId() → Resource::id(): Id. This moves ID definition from an imperative method into a declarative field object that also carries type constraints, validation rules, and write permissions. Any resource with custom ID logic needs re-modelling, not just renaming.
• Behavioural / silent — ToOne custom deserializers now receive the resolved model instead of the raw relationship object. This will not raise an error; it will produce wrong data if the deserializer was written against the old contract. This is the highest-risk item in the release.

Technical risk

• Release candidate status. An RC with this breadth of breaking change means the public API is still settling. Pinning to a moving target is risky; pinning to rc.1 indefinitely accrues drift.
• Unbounded blast radius. The changes touch every resource class, every custom error provider, every custom deserializer, and any extension registrations. Effort scales with how much customisation the codebase carries, which is not knowable without an inventory.
• Error document contract shift. Errors now represent a single error, with multiples wrapped in JsonApiErrorsException. Clients that assumed a stable array shape may break on parsing even though the JSON:API spec is still honoured.
• OpenAPI drift. The schema generation refactor will almost certainly alter the emitted spec. Any generated SDKs, contract tests, or downstream consumers must be re-baselined.
• ID writability is a security-adjacent change. Id::writableOnCreate() allows client-generated IDs. That is a deliberate capability, but it needs a policy decision per resource, not a default.

Key questions

• What is the supported Laravel and PHP version matrix for rc.1, and does it match our current runtime?
• Is there a published upgrade guide, and ideally Rector rules or a codemod, for the getId() → id(): Id migration?
• What is the expected GA timeline, and how many additional breaking changes are anticipated between rc.1 and GA?
• Are transitional shims or deprecation layers planned for any removed APIs, or is this a hard cut?
• What is the maintenance and support model — single maintainer, funded, or community? What is the historical cadence of breaking releases?
• Does enabling client-generated IDs require a schema change (non-auto-increment or UUID columns) on the affected tables?

Integration Approach

Stack fit

The package is idiomatic Laravel and composes cleanly with the surrounding stack: routing and middleware are unchanged, authorization continues through Laravel policies and gates, and authentication (Sanctum/Passport) is orthogonal to the upgrade. The new Endpoint::headers(), Endpoint::response(), and endpoint-hook surface actually improves fit for teams that previously had to reach around the package to customise responses. The asynchronous processing support (Create::async() → 202, Show::seeOther() → 303) is a genuine architectural fit for queue-backed writes and fits naturally with Laravel's queue primitives.

Migration path

1. Inventory before touching code. Grep the codebase for every removed symbol and every overridden method in the breaking-changes list. Produce a per-file effort estimate. Do not estimate from the release notes alone.
2. Establish a behavioural baseline. Capture the current OpenAPI document and a corpus of representative request/response pairs (including error responses) as golden files. This is the only reliable way to catch the silent deserializer change and schema drift.
3. Upgrade on a branch with the full test suite green before and after. Fix compile-time failures first, then diff against the golden corpus, then investigate every difference deliberately.
4. Re-baseline the OpenAPI document and diff it against the previous version. Treat any difference as a client-facing change requiring sign-off.
5. Land the breaking-change migration and feature adoption as separate PRs. Do not mix "make it compile again" with "adopt resource links / profiles / new Type classes." The former is a debt payment; the latter is scope.

Compatibility

• Removed APIs are hard breaks with no fallback; there is no compatibility mode.
• The error-shape change is a wire-level contract change. Verify against real client code, not just the spec.
• Profile support alters Accept parsing and Content-Type emission. Cursor pagination now auto-activates the cursor-pagination profile — this is a response-header change that existing clients may not expect.
• New endpoints split Show/Update into aggregate *Resource and *Relationship endpoints. Route names and generated schema paths may shift; check any hardcoded client routes.

Sequencing

• Phase 0 — Decision. Confirm GA timeline and support model before committing. If GA is imminent, wait; migrating twice through breaking changes is wasted effort.
• Phase 1 — Foundations. Error provider signature, JsonApiError trait, helper removals, namespace moves. Low ambiguity, high error visibility, unblocks the rest.
• Phase 2 — Resource identity. Resource::id(): Id conversion, with an explicit per-resource decision on type constraints and writability. Highest effort and highest data-integrity exposure.
• Phase 3 — Behavioural verification. Deserializer audit, OpenAPI re-baseline, client contract sign-off.
• Phase 4 — Capability adoption. Resource links, async processing, profiles, extended Type schema support — each as an independently justified piece of scope, not bundled into the upgrade.

Operational Impact

Maintenance

Expect continued churn while the package is in RC. Budget recurring maintenance rather than a one-time upgrade cost: pin the version explicitly, track release notes as a standing agenda item, and avoid floating constraints. Consider a thin internal adapter layer around the highest-churn surfaces (error providers, ID resolution) to shrink the blast radius of the next breaking release.

Support

This is community OSS with a single-maintainer risk profile. There is no vendor SLA. The mitigation is internal: at least two engineers who understand the package internals, a documented upgrade runbook, and a decision record explaining any place we diverge from upstream conventions. Without that, the next breaking release becomes a heroic single-person effort.

Scaling

The release is net-positive here. Serialization performance optimisations directly reduce per-request cost on the hottest path in a JSON:API service. Cursor pagination range truncation (Page::$rangeTruncated) matters for large or unbounded result sets, where truncated ranges were previously ambiguous to clients. Asynchronous processing lets long-running create operations leave the request cycle, which improves tail latency and reduces timeout-driven retries. Resource and relationship links, plus richer Type support, reduce ad-hoc custom serialization that typically accumulates as a service grows.

Failure modes

• Boot/dispatch fatals from removed helpers and signatures — noisy but safe; caught by any smoke test.
• Silent data corruption from ToOne deserializers receiving a resolved model. Highest severity, lowest detectability. Mitigate with explicit integration tests per deserializer.
• Client parse failures from the single-error document shape and from multi-error wrapping. Detectable only with contract tests against real clients.
• Generated SDK mismatch from OpenAPI drift — often discovered downstream, at which point the fix cost is external.
• ID writability misconfiguration allowing client-supplied IDs to collide with or overwrite existing records. This is a correctness and authorization issue; require explicit per-resource review and, ideally, a policy-level guard.
• Header/negotiation surprises from automatic profile activation on cursor pagination, affecting caches and clients that key on Content-Type.

Ramp-up

The conceptual load is unevenly distributed. The error provider and trait changes are an afternoon. The Id field, SchemaContext, the new Type hierarchy (Obj, AnyOf, AllOf, OneOf, Not, nullable()), and endpoint hooks represent a genuine learning curve — the mental model moves from imperative overrides to declarative field definitions. Plan for a spike by one engineer, a written internal pattern document, and a staged rollout through a non-critical API surface before touching customer-facing endpoints. Allocate meaningful time to the OpenAPI re-baseline; it is consistently underestimated and is the step most likely to surface unexpected client impact.

Recommendation. Treat rc.1 as a planned migration, not a routine dependency bump. Gate the work on an inventory, a captured behavioural baseline, and a clear answer on GA timing; sequence the breaking changes ahead of feature adoption; and require explicit sign-off on the ID writability decision and the error-shape change before anything reaches production.