Ai Admin Jsonadm Laravel Package

Getting Started

Start by installing the package via Composer (composer require aimeos/ai-admin-jsonadm) and ensuring the Aimeos admin interface is properly configured in config/shop.php. The package provides a JSON API for administrative operations—its primary use is as a backend for custom admin UIs or headless systems. First, familiarize yourself with the default endpoints at /jsonadm/{resource}, where {resource} corresponds to Aimeos entities (e.g., product, catalog, customer). Send authenticated requests (using Aimeos authentication middleware or a custom provider) with proper JSON payloads. Begin with a simple read operation (e.g., GET /jsonadm/product?include=media) to confirm setup.

Implementation Patterns

• CRUD via RESTful JSON: Use standard HTTP methods (GET, POST, PATCH, DELETE) on /jsonadm/{resource} to manage entities. Include include query parameters to eagerly load relationships (e.g., ?include=property,catalog,price).
• Bulk operations: Leverage the batch endpoint (POST /jsonadm/batch) to perform compound operations (e.g., create 10 products in one request), reducing round trips.
• Custom extensions: Extend existing resources by subclassing \Aimeos\Admin\JsonAdm\Base and registering them in config/admin.php. Override methods like save() to inject business logic (e.g., syncing to an external PIM).
• Headless integration: Pair with frontend frameworks (React, Vue) by building a thin API layer—use CORS middleware and JSON-API compliant payloads (data, attributes, relationships) for predictable client-side handling.

Gotchas and Tips

• Authentication pitfalls: The package assumes Aimeos session-based auth by default; if using API tokens (e.g., JWT), ensure your auth guard is explicitly configured in config/admin.php under paths/admin/jsonadm/auth.
• Validation quirks: Errors return full exception traces by default in debug mode—always set debug => false in production. Use error.code and error.detail to programmatically handle issues (e.g., duplicate SKU).
• Performance tuning: Avoid N+1 queries by using include judiciously; large result sets should be paginated (?page[offset]=0&page[limit]=50). For huge catalogs, consider &filter with indexed fields (e.g., product.status, product.mtime).
• Extensibility hooks: Extend Aimeos\Admin\JsonAdm\Product\Standard to intercept before/after operations using beforeSave() or afterGet() methods—ideal for adding audit logs or cache invalidation.