Json Api Server Laravel Package

Product Decisions This Supports

• API contract standard: JSON:API vs. bespoke REST. This release materially closes the remaining spec gaps — profiles, async processing (202 Accepted / 303 See Other), resource and relationship links, and richer type schemas (Obj, Any, AnyOf, AllOf, OneOf, Not, plus nullable() on sub-types). That means "adopt JSON:API" becomes a defensible decision rather than a compromise, because you no longer need custom glue for the edge cases clients will eventually ask for.
• Build vs. buy for the API layer. Serialization, sparse fieldsets, compound documents, filtering/sorting/pagination validation, error objects, and OpenAPI schema generation all come from one dependency. The alternative — hand-rolling these as internal ApiResponse classes — is a multi-sprint investment that will drift from the spec over time.
• Roadmap sequencing for client-facing capabilities. Several features map directly to product asks you likely already have in the backlog:
  • Client-generated IDs via Id::writableOnCreate() — unblocks offline-first / optimistic mobile flows and idempotent retries.
  • Async processing hooks — long-running operations (exports, report generation, bulk imports) can return 202 with a status resource instead of timing out.
  • Cursor pagination with Page::$rangeTruncated — enables infinite-scroll feeds and stable pagination over large, changing datasets.
  • Profiles (Context::profileRequested() / activateProfile()) — lets you ship opt-in extensions without forking the API version, a cheaper path than /v2 for additive changes.
• Documentation and SDK cost. OpenAPI schema generation is now driven by the same definitions that power validation and serialization, so API docs stop being a separate deliverable. This is the line item that most often justifies adoption on its own — it lowers partner onboarding cost and makes generated client SDKs viable.
• Error contract and support burden. Per-exception error classes plus JsonApi::errors() overrides give you a consistent, client-parseable error shape and a single place to tune detail messaging (including :key substitutions for localization). Fewer "why did the API return this?" tickets.
• Versioning and release-risk policy. v1.0.0-rc.1 is a release candidate with substantial breaking changes (renamed Resource::id(), ErrorProvider singularization, trait rename, removed json_api_response() and Context::queryParam(), moved Extension\Atomic). The product decision here is a governance one: pin exact versions, and if any code was written against earlier RCs, budget a migration ticket before the GA cut.

When to Consider This Package

Good fit when:

• You are building a public or partner-facing API on Laravel/PHP backed by Eloquent models.
• A consumer, spec, or internal standard already requires JSON:API — or you want compound documents, include, sparse fieldsets, and relationship endpoints without inventing conventions.
• You want OpenAPI documentation and validation derived from a single source of truth.
• You need the newer capabilities specifically: client-generated IDs, async/long-running operations, cursor pagination, or opt-in profiles.
• Your team can absorb migration work between pre-1.0 releases.

Look elsewhere when:

• The API is internal, single-consumer, or RPC-shaped — JSON:API's document structure and media-type negotiation are overhead you'll never amortize.
• The stack isn't Laravel/PHP, or resources aren't Eloquent-backed.
• You require a stable, GA public API surface today and cannot tolerate breaking changes on upgrade. RC status is a real constraint, not a formality.
• The team has no JSON:API familiarity; the spec's conventions (linkage, related vs. relationships endpoints) impose a real learning curve that will show up in estimates.
• The product direction is GraphQL — this is not a substitute and mixing both raises cost.

How to Pitch It (Stakeholders)

For executives: We're standardizing our API on JSON:API using a mature Laravel package rather than building the conventions ourselves. That gets us spec-compliant behavior, machine-generated OpenAPI documentation, and standard error responses out of the box — which reduces integration time for partners and mobile clients, and removes a recurring source of support tickets. It also unlocks capabilities we'd otherwise build: client-generated IDs for offline-first mobile, async responses for long-running jobs, and cursor pagination for large datasets. The caveat is timing: the current release is a release candidate with breaking changes, so we pin the version, treat upgrades as planned tickets, and target GA before we commit any external partner to the contract.

For engineering: The package now covers query-parameter validation, OpenAPI schema generation, resource/relationship links, and JSON:API profiles, with extension hooks (Endpoint::headers(), response(), schema(), Create::saved(), Update::saved()) so we don't fork it for bespoke behavior. The RC changes several public APIs — Resource::id() returning an Id field, singular ErrorProvider::getJsonApiError(), the JsonApiError trait rename, and removed helpers (json_api_response(), Context::queryParam()) — so plan a short migration pass and avoid building against removed surfaces.