Ai Client Jsonapi Laravel Package

Getting Started

Install via Composer: composer require aimeos/ai-client-jsonapi. Once installed, the package registers Laravel facade aliases and service providers automatically. Start by configuring the Aimeos JSON API routes in routes/api.php (e.g., Route::prefix('jsonapi')->group(\Aimeos\AiClient\JsonApi\Support\Facades\Routes::class . '::routes');). The first use case is typically fetching product lists: GET /jsonapi/commerce/products?filter[status]=1&include=media,price,catalog. Responses follow the JSON API specification (application/vnd.api+json), making them ready for frontend consumption.

Implementation Patterns

• Controller Integration: Use the JsonapiController trait in your custom Laravel controllers to add Aimeos JSON API endpoints alongside other routes.
• Client-Side Caching: Leverage the built-in ETag and If-None-Match support—responses include ETag headers; clients can use conditional requests to reduce bandwidth.
• Custom Resource Types: Extend core resources (e.g., Product, Basket) via Laravel’s service provider to add custom fields or relationships (e.g., include=attributes,customOptions).
• Authentication Layer: Integrate with Laravel Passport or Sanctum—use middleware('auth:sanctum') on routes requiring authenticated users (e.g., /jsonapi/commerce/basket for cart updates).
• Request Validation: Override request validation classes (e.g., Aimeos\AiClient\JsonApi\JsonapiRequest) in config/aimeos.php under 'client/jsonapi' => ['request' => \App\JsonApi\CustomRequest::class] to adjust parameter parsing.

Gotchas and Tips

• Double Encoding Pitfall: Avoid double-encoding JSON in responses—ensure no middleware (e.g., custom json() helpers) re-encodes the Aimeos response.
• Route Conflicts: The package maps commerce/ prefixes (e.g., /jsonapi/commerce/products). Avoid overlapping custom API paths unless explicitly namespaced.
• Pagination Defaults: Default page size is 10. Adjust via ?page[size]=50 or globally in config/aimeos.php: 'client/jsonapi' => ['page' => ['size' => 25]].
• Debugging: Enable detailed error responses by setting 'debug' => true in config/aimeos.php—but never in production. Check storage/logs/aimeos.log for server-side JSON API errors.
• Extending Relationships: To add custom relationships like reviews to products, bind a custom JsonApi\Adapter\Product in the service provider’s register() method: app()->singleton(\Aimeos\AiClient\JsonApi\Adapter\Product::class, \App\JsonApi\Adapter\CustomProduct::class);.