Json Api Laravel Package

Technical Evaluation

What it is: tobscure/json-api is a standalone PHP serializer that turns application objects into JSON:API 1.0 documents — data, included, relationships, links, meta, errors — with serializers, sparse fieldsets, compound documents, and error objects. It is a presentation-layer library, not a framework: it does not route, query, paginate, or validate.

Architecture fit: Good fit only if a JSON:API contract is already demanded — an Ember/jsonapi.js front end, a spec-driven public API, or an existing client that expects compound documents and included semantics. Poor fit for a typical Laravel app doing plain REST/JSON: Laravel API Resources give the same outcome with fewer moving parts and no orphaned dependency. Where it does fit, it fits cleanly at the controller→response boundary and composes with Eloquent without changing domain code.

Integration feasibility: Moderate, with hand-written glue. The package itself is a small, dependency-light library and is understandable in a day. The friction is environmental: the last release is March 2017, so Composer constraints, PHP version ceilings, and Laravel adapter expectations are all stale. The companion tobscure/laravel-json-api integration (service provider, facade, exception handling) is also abandoned, meaning the Laravel-specific wiring — provider registration, exception renderer mapping ValidationException/NotFoundHttpException to JSON:API errors, pagination link generation — is ours to build and own.

Technical risk: High and asymmetric.

• Runtime: Likely fails or emits deprecations on PHP 8.x (ArrayAccess/Serializable return types, dynamic properties). Needs a verified compatibility pass before any commitment.
• Spec drift: JSON:API 1.1 (2022) added @atomic operations, revised error codes, and link/pagination refinements. This library will never support them. Locking in means locking clients to 1.0.
• Supply chain: Archived, no maintainer, no advisories, and the repository is recorded as unknown in the metadata — provenance is unverifiable, so any use must be pinned to a commit SHA and mirrored into internal VCS.
• Dependency pinning (highest severity): stale illuminate/support constraints can block Laravel upgrades, forcing the team to choose between framework security patches and the serializer.

Key questions:

1. Which JSON:API version do consuming clients actually require — 1.0, or is 1.1 expected?
2. What is the PHP runtime target, and has the library been executed on it?
3. Is fork-and-own explicitly approved, with a named owner and budget?
4. Are laravel-json-api (formerly cloudcreativity/json-api) or neomerx/json-api viable alternatives, and why were they rejected?
5. Do we need relationship endpoints, pagination adapters, and sorting/filtering conventions that this package does not provide?
6. Can we confirm the exact commit being installed, and is it mirrored internally?

Integration Approach

Stack fit: Treat it strictly as a presenter. Controllers and query objects build and eager-load Eloquent models; serializers only shape output. Do not let include/sparse-fieldset parsing drive query construction without an explicit adapter layer, or the query layer becomes implicit and untestable.

Migration path:

1. Fork into internal VCS, tag a pinned version, and add a Composer vcs/path repository entry — do not depend on the public Packagist artifact.
2. Run a PHP 8 compatibility pass (return types, Stringable, removed helpers), relax composer.json version ceilings, and stand up a CI matrix on the PHP versions actually deployed.
3. Replace the abandoned Laravel adapter with an in-house service provider: bind serializers, register an exception renderer that emits JSON:API errors, and centralize link/meta generation.
4. Extract pagination and include-parsing into app-owned classes so they are unit-testable and reusable if we later swap libraries.

Compatibility: Verify the illuminate/support constraint against the target Laravel major first — this is the go/no-go gate. Confirm behavior under the framework's HTTP layer (content negotiation, application/vnd.api+json media type) and check for reliance on global helpers removed or deprecated since Laravel 6.

Sequencing: (a) 2–3 day spike on a single representative resource; (b) define conventions for includes, sparse fieldsets, pagination links, and error shape; (c) add contract tests run against a JSON:API schema validator; (d) only then broaden to the full resource surface. Do the fork and CI work before writing new endpoints, not after.

Operational Impact

Maintenance: We own it outright. Small codebase (low thousands of lines), so tractable — budget roughly 5–10% of one engineer ongoing, spiking at PHP major upgrades and any spec work. Every upgrade of PHP or Laravel becomes a manual verification task with no upstream to lean on.

Support: None. No maintainer, no advisories, no active issue tracker, no meaningful community momentum since 2017. Institutional knowledge concentrates in whoever performs the fork, which is a single-point-of-failure risk unless the fork is documented and reviewed like first-party code.

Scaling: Serialization is in-process CPU, so horizontal scaling is the standard PHP answer. The real cost is payload and query shape: compound documents grow with include depth, and careless includes produce N+1 queries or oversized included arrays. Enforce a maximum include depth, honor sparse fieldsets at the query level, and consider ETag/edge caching. There is no built-in pagination adapter — pagination correctness is an application responsibility and a recurring source of client-visible bugs.

Failure modes:

• Fatal errors on a PHP minor upgrade, discovered in production rather than CI.
• Silent spec drift: documents that validate loosely but are rejected by strict clients.
• Unbounded include/recursion requests used as a resource-exhaustion vector.
• Thin exception mapping leaking stack traces or non-conforming error bodies.
• Composer resolution conflicts that block framework security patches — the failure with the longest blast radius.

Ramp-up: A mid-level Laravel developer is productive in 1–2 days and safe with serializers, includes, and sparse fieldsets in about a week. Add a short internal guide plus fixture-based tests. The longer pole is onboarding the maintainer of the fork, not the consumer — plan for at least two people who can patch it.