Laravel Apiable Laravel Package

Product Decisions This Supports

• Standardizing API responses across a Laravel-based microservices or monolithic architecture, ensuring consistency with the JSON:API spec (data, links, meta, included).
• Accelerating API development by reducing boilerplate for serializing Eloquent models into standardized JSON:API responses, cutting ~30% of manual controller/transformer code.
• Enabling modular API design for teams building APIs with shared resources (e.g., users, posts), where relationships (e.g., author, comments) must be consistently exposed.
• Roadmap item: Adopting JSON:API for a new greenfield project or migrating an existing API to improve client compatibility (e.g., React/Vue/SPA frontends).
• Build vs. Buy: Avoid reinventing a JSON:API serializer (e.g., Fractal, Laravel's built-in Resource classes) when the package aligns with your team's Laravel expertise and JSON:API needs. As of 4.5.0 the "buy" case is stronger: built-in negated filters (AllowedFilter::notEqual() / notLike()) cover exclusion-style querying (e.g., "all active users except status=suspended") that previously required custom query code or ad-hoc endpoints.
• Use cases:
  • Public APIs for third-party consumption (e.g., mobile apps, partner integrations).
  • Internal APIs where consistency across services is critical (e.g., microservices communicating via API contracts).
  • Projects requiring fine-grained control over relationships, pagination, sparse fieldsets (?fields[posts]=title,body), and now filter operators (positive and negated, comma-separated values ANDed together).
  • Mixed-resource endpoints — search results, activity feeds, or dashboards returning heterogeneous models — which now serialize correctly in collections and paginated responses via Apiable::modelResourceMap(), with an explicitly supplied resource class still winning.

When to Consider This Package

• Adopt if:

  • Your Laravel API must comply with the JSON:API spec (e.g., for interoperability with existing clients or ecosystem tools).
  • You're building a resource-heavy API with complex relationships (e.g., nested hasMany, polymorphic associations) that require standardized serialization.
  • Your team prefers Laravel-native solutions over Fractal or generic PHP libraries.
  • You need built-in support for JSON:API features like sparse fieldsets (?fields[users]=name,email), pagination metadata, relationship loading (?include=author), and negated filtering (notEqual, notLike) without writing custom query scopes.
  • You're building search, admin, or moderation UIs where exclusion filters ("everything except archived," "titles not matching internal-*") are a first-class product requirement rather than a one-off.
  • You serve polymorphic or mixed-model collections (feeds, notifications, global search) and want per-model resource resolution handled for you.
  • You're using Laravel 10+ (package supports latest PHP/Laravel versions).

• Look elsewhere if:

  • Your API uses non-JSON:API formats (e.g., GraphQL, REST with custom schemas) or requires GraphQL-like flexibility.
  • You need advanced caching, real-time updates (WebSockets), or complex full-text/aggregation search; this package focuses on request/response serialization and query filtering, not search infrastructure.
  • Your team lacks Laravel/PHP expertise; the package assumes familiarity with Eloquent and the service container.
  • You're constrained by MIT license incompatibility (rare, but check your org's policies).
  • You require enterprise support or audit trails (this is a community package with no commercial backing).
  • Your API is simple (e.g., CRUD with no relationships or filtering) and doesn't justify the abstraction layer.

How to Pitch It (Stakeholders)

For Executives: "This package lets us standardize our Laravel APIs on JSON:API—a widely adopted spec that reduces client-side parsing complexity and future-proofs our integrations. It cuts development time by automating response formatting (relationships, pagination, sparse fieldsets) and now covers the filtering logic product keeps asking for, including exclusion-style filters ('show everything except archived'), without custom backend work per feature. For example, [Company X] used JSON:API to reduce their mobile app's API payload size by 40% and add features like sparse fieldsets without backend changes. The MIT license and active maintenance make it a low-risk, high-reward choice for our [greenfield/migration] project."

For Engineering: *"Laravel-Apiable replaces manual Resource classes or Fractal with a lightweight, Laravel-native way to serialize Eloquent models into JSON:API. Key benefits:

• DRY responses: Define an Apiable trait/interface once per model; no duplicated toArray() logic.
• Relationships out of the box: hasOne, belongsTo, and polymorphic relationships via ?include= (e.g., /posts?include=author,comments).
• Spec compliance: Automatically produces links, meta, and included.
• Filtering built in (4.5.0): AllowedFilter::notEqual() / notLike() join the positive operators; comma-separated values combine with AND, so exclusion filters don't need bespoke scopes.

What changed in 4.5.0 that de-risks the pilot:

• Sparse fieldsets no longer break relationship hydration — the primary/foreign/morph keys Eloquent needs are retained internally but kept out of the response attributes, and explicitly requested appends stay visible. This removes a real correctness/payload-hygiene concern for ?include= + ?fields[...] combinations.
• Mixed-model collections and paginated responses now resolve resources via modelResourceMap(), matching single-resource behavior; per-model resource classes are honored and an explicit resource class still takes precedence. Previously a reason to hand-roll serializers for feeds/search endpoints.
• Default filters declared via both controller attributes and fluent config are now idempotent instead of silently producing a duplicated array and an empty query — a subtle, hard-to-debug failure mode eliminated for teams layering config conventions.

Tradeoff: We adopt JSON:API for all new APIs (or migrate existing ones), and filtering semantics are still operator-based rather than a full query language. The payoff is consistency, less custom serialization code, and tooling support (e.g., Skore for API docs). Proposal: Pilot this for our [Project Y] API—ideally one with a mixed-resource feed or exclusion-filter requirements, where 4.5.0 delivers the most value—and measure dev time saved vs. custom solutions."*