Json Api Laravel Package

Product Decisions This Supports

• Public/partner API surface (v1 or v2): JSON:API gives you a standardized contract — application/vnd.api+json content negotiation, structured error objects, pagination links, and relationship endpoints. This package supplies that plumbing so the team spends its time on domain logic rather than spec compliance.
• Build vs. buy on API conventions: A compliant implementation of content negotiation, error documents, sparse fieldsets, includes/compound documents, and pagination is typically weeks of engineering plus ongoing edge-case work. Adopting a library converts that into an integration and audit task — a favorable trade if the library is trustworthy.
• Multi-client roadmap: Mobile (iOS/Android), web SPA, and third-party integrators all benefit from a single, predictable response shape; compound documents and include reduce round trips and client-side join logic, which is a measurable latency and support-ticket win.
• Standardization vs. bespoke JSON: Choosing JSON:API (and by extension this package) is a commitment to a documented, tooling-supported convention. It constrains our response design in exchange for interoperability, cacheability, and fewer one-off client integrations. This is a strategic API-governance decision, not just a dependency choice.
• Internal service contracts: If multiple teams own resources, a spec-backed envelope for errors and pagination reduces cross-team negotiation and makes contract tests meaningful.
• Not supported: This is a serialization/protocol layer. It does not give you auth, rate limiting, versioning policy, OpenAPI docs, or observability — those remain product and platform decisions you own.

When to Consider This Package

Consider it when:

• You are building or refactoring a PHP API and have already decided JSON:API is the target contract (or are evaluating it seriously).
• You need only the spec plumbing — negotiation, error handling, pagination, CRUD resource semantics — and are content to own routing, authorization, persistence, and validation.
• Your schema/resource construction can benefit from container-based resolution (added in v1.5.1): schema discovery can now resolve its dependencies through a PSR-11-style container, which reduces hand-wiring for configurable or per-tenant schema definitions and makes it easier to inject environment-specific or policy-driven schemas.
• You are not Laravel-locked and can live with Slick-framework conventions. v1.5.1's DI work confirms this package is developed as a Slick component first; Laravel's service container is PSR-11 compatible, so bridging is feasible, but expect glue code and no Eloquent/routing/filtering adapters.
• Engineering can vendor, fork, or fully audit a small codebase, and you can absorb maintenance if upstream stalls.
• Legal has cleared the license (see risk below) or you are using it in a context where that is acceptable.
• You want a timeboxed spike to validate JSON:API ergonomics before committing to a longer build.

Look elsewhere when:

• License is unresolved. The repository reports NOASSERTION, meaning the license could not be identified. For any commercial or distributed product this is a hard blocker until counsel signs off — treat it as a gating item, not a footnote. Nothing in v1.5.1 changes this.
• Maturity and support matter. Still ~1 star, effectively no dependents, and a single-maintainer profile: no community triage, no documented security advisory process, bus factor of one. v1.5.1 is evidence the project is alive — a patch release with a real feature and refreshed dependencies — but "alive" is not "supported." If the API is customer-facing and revenue-bearing, that remains a material operational risk.
• You just need conventional REST JSON. Laravel API Resources, Fractal, or hand-rolled transformers are lower-risk and better supported if strict JSON:API compliance isn't a requirement.
• You need a first-class Laravel integration with routing, filters, and Eloquent adapters out of the box — mature alternatives in that space are a better fit and reduce glue code.
• You are pinned to doctrine/collections 1.x. v1.5.1 widened the constraint to ^2.2 || ^3.0 and refreshed Symfony components; it did not keep 1.x support. Check for constraint conflicts with the rest of your dependency graph before estimating — this is the most likely source of a surprise integration day.
• The package is coupled to Slick's HTTP/message abstractions. The v1.5.1 DI-in-schema-discovery feature is a Slick-framework idiom, which is a useful data point: assume the package expects a Slick-style container and HTTP stack unless you verify otherwise. Integration cost rises and portability falls; wrap it.

How to Pitch It (Stakeholders)

To executives: This is a small PHP library that makes our API speak JSON:API, an established open standard for API responses. Adopting the standard means every client — web, mobile, partners — consumes the same predictable shape for data, errors, and paging, which shortens integration work and reduces support load as we add consumers. The latest release (v1.5.1) is a maintenance patch: it adds dependency-injection support for schema definitions and refreshes dependencies. That is a positive signal — the project is being actively maintained rather than abandoned — but it does not change the two facts that gate us: the license is still not clearly declared, and the project still has effectively no user base and one maintainer. I continue to recommend a short, timeboxed technical spike rather than a commitment. The decision in front of us is whether JSON:API is our API contract; the library is a replaceable implementation detail.

To engineering: It covers content negotiation, error documents, pagination, and resource fetch/create/update/delete semantics, so we don't reimplement the spec. We still own routing, auth, validation, persistence, and tests. What's new in v1.5.1: (1) schema discovery can now resolve its dependencies through a DI container, so schema objects can be constructed with injected collaborators instead of hardcoded new calls — useful if we want per-tenant or policy-driven schema sets, and a hint that the package expects a Slick-style container we'd need to bridge to Laravel's; (2) doctrine/collections moved to ^2.2 || ^3.0 with Symfony components refreshed — non-breaking on the surface, but verify our lockfile resolves cleanly, since 1.x of that package is no longer allowed. The codebase is small enough to vendor and audit, and we should wrap it behind a thin adapter so the protocol layer can be swapped without touching domain code. Open items before adoption remain: license clarification, a security and quality review, and confirmation of the Slick framework coupling — which v1.5.1 makes more likely, not less. Plan for a one-to-two week spike producing a working vertical slice plus a written risk assessment.

Recommendation: Evaluate now, adopt conditionally. Proceed only if the license is cleared and the spike shows clean integration; otherwise use the spike to justify either a maintained alternative or a minimal in-house serializer scoped to the subset of JSON:API we actually need.