Quick Start
This guide walks you through building a complete REST API for a Product resource in under 5 minutes. By the end, you’ll have a fully functional API with filtering, pagination, and relation loading.Prerequisites
- PHP 8.0 or higher
- Laravel 12.x
- Composer
Installation
Install the Package
Install via Composer:The package uses Laravel’s auto-discovery, so no need to register the service provider.
That’s it! The package is installed and ready to use. No migrations, no additional setup required.
Basic Setup
Let’s build a Product API with category relationships. We’ll create four files:Step 1: Create the Model
Createapp/Models/Product.php:
app/Models/Product.php
The
RELATIONS constant is critical for security. Only relations listed here can be queried or loaded. This prevents attackers from accessing unintended data.Step 2: Create the Service
Createapp/Services/ProductService.php:
app/Services/ProductService.php
The service is minimal because all standard CRUD logic is inherited. You can override methods to add custom business logic when needed.
Step 3: Create the Controller
Createapp/Http/Controllers/Api/ProductController.php:
app/Http/Controllers/Api/ProductController.php
Step 4: Define Routes
Add toroutes/api.php:
routes/api.php
Laravel’s
apiResource automatically creates these routes:GET /api/v1/products→ indexPOST /api/v1/products→ storeGET /api/v1/products/{id}→ showPUT /api/v1/products/{id}→ updateDELETE /api/v1/products/{id}→ destroy
Test Your API
Your API is now ready! Let’s test it:Create a Product
List Products with Filtering
Load with Relations
Filter by Related Data
Update a Product
Bulk Update Multiple Products
Delete a Product
What You Get Out of the Box
With these four files, you now have:Complete CRUD
Create, read, update, and delete operations with proper HTTP methods
Dynamic Filtering
Complex queries with operators and powerful filtering capabilities
Relation Loading
Eager load relations with field selection
Pagination
Both offset-based and cursor-based pagination
Sorting
Order by any field in ascending or descending order
Bulk Operations
Update multiple records in a single request
Security
Relation allowlists, operator allowlists, query depth limits
Error Handling
Automatic database error parsing with user-friendly messages
Advanced Query Examples
Complex Filtering with Nested Logic
Multiple Relations with Field Selection
Nested Relation Loading
Filtering on Nested Relations
Cursor Pagination for Infinite Scroll
Next Steps
Now that you have a working API, explore these advanced features:Configuration Guide
Learn about environment variables, caching, and configuration options
Basic Usage
Detailed guide to all query parameters and filtering options
Advanced Usage
Hierarchical data, role-based fields, exports, and custom logic
API Reference
Complete reference for all methods, parameters, and configurations
Common Next Tasks
Add Validation Rules
Add Validation Rules
Create a FormRequest class extending Update your controller to use it:
BaseFormRequest:Enable Caching
Enable Caching
Add to your Cache is automatically applied to read operations and invalidated on writes.
.env:Add Role-Based Field Restrictions
Add Role-Based Field Restrictions
In your model:Now only users with the ‘admin’ role can modify these fields.
Enable Hierarchical Categories
Enable Hierarchical Categories
For tree structures (like categories):Query the hierarchy:
Congratulations! You’ve built a production-ready REST API with advanced filtering, relations, and pagination in just a few minutes.
Troubleshooting
Error: Relation 'category' is not allowed
Error: Relation 'category' is not allowed
Make sure the relation is listed in your model’s
RELATIONS constant:No query results with filters
No query results with filters
Check your operator syntax. Format must be:
Incorrect:
field|operator|valueCorrect: "price|>=|100"Incorrect:
"price >= 100"Foreign key not included in relation fields
Foreign key not included in relation fields
The package automatically includes foreign keys. Don’t worry if you specify
category:id,name - the category_id FK is added automatically.Cache not working
Cache not working
Ensure caching is enabled in config and your cache driver is properly configured:
Get Help
If you run into issues:- Check the Troubleshooting Guide for common problems
- Review the FAQ for frequently asked questions
- Open an issue on GitHub
- Read the full Documentation for detailed information
Ready to dive deeper?
Explore the complete feature set in the Basic Usage guide