api-resource

Instruction file imported from jm-sky/saasbase-api (.cursor/rules/api-resource.mdc). Copyright stays with the author.

description: globs: *Resource.php,*Controller.php alwaysApply: false

• Controllers must use the HasIndexQuery trait for index endpoints.

  • Use Spatie Query Builder for all index queries.
  • Define $modelClass, $filters, $sorts, and $defaultSort in the controller.
  • See ProductController.php for reference.

• Controllers must use AdvancedFilter and ComboSearchFilter for flexible filtering.

  • Add AllowedFilter::custom('search', new ComboSearchFilter([...])) for multi-field search.
  • Use AllowedFilter::custom('field', new AdvancedFilter()) for advanced per-field filtering.
  • See ProductController.php.

• Controllers must use policies for authorization.

  • Use $this->authorize('action', $model) in show, update, and destroy methods.
  • See ProjectController.php.

• All single model API responses must be wrapped in a data key.

  • This is
  • This provides flexibility for adding extra content (e.g., message, meta) in the future and ensures consistency with paginated/multi-item responses.

• DO:

  • Use Resources for API responses.
  • Use DTOs for internal data movement.
  • Use camelCase for all response keys.
  • Include pagination meta for paginated endpoints.
  • Use policies for all resource actions.
  • Wrap all single model responses in a data key.

• DON'T:

  • Return Eloquent models or raw arrays directly.
  • Use snake_case in API responses.
  • Omit authorization checks.
  • Return single models without a data wrapper.

• References:

  • ProductController.php
  • ProjectController.php
  • HasIndexQuery.php
  • AdvancedFilter.php
  • ComboSearchFilter.php