Laravel API Development
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Analyze existing API patterns
- fuse-ai-pilot:research-expert - Verify Laravel API docs via Context7
- mcp__context7__query-docs - Check API Resources and Sanctum patterns
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
Build RESTful APIs with Laravel using API Resources for response transformation and Sanctum for authentication.
| Component |
Purpose |
| Controllers |
Handle requests, delegate to services |
| Form Requests |
Validate input, authorize actions |
| API Resources |
Transform models to JSON |
| Middleware |
Auth, rate limiting, CORS |
| Routes |
Versioned endpoints with groups |
| Pagination |
Offset/cursor pagination |
| HTTP Client |
Consume external APIs |
Critical Rules
- Always use API Resources - Never return Eloquent models directly
- Versioned routes - Prefix with
/v1/, /v2/
- Validate all input - Use Form Requests, not inline validation
- Rate limiting - Configure per-route limits
- Consistent responses - Same structure, proper status codes
- Use services - Keep controllers thin
- Eager load - Prevent N+1 with
with() before pagination
Reference Guide
Core Concepts
| Topic |
Reference |
When to consult |
| Routing |
routing.md |
Defining versioned API routes |
| Controllers |
controllers.md |
Controller patterns, resource methods |
| Middleware |
middleware.md |
Route protection, request filtering |
| Validation |
validation.md |
Form Requests, validation rules |
Request/Response
| Topic |
Reference |
When to consult |
| Requests |
requests.md |
Accessing input, files, headers |
| Responses |
responses.md |
API Resources, status codes |
| Pagination |
pagination.md |
Offset/cursor pagination |
Advanced
| Topic |
Reference |
When to consult |
| Rate Limiting |
rate-limiting.md |
Throttle configuration |
| HTTP Client |
http-client.md |
Consuming external APIs |
| URLs |
urls.md |
URL generation, signed URLs |
| Strings |
strings.md |
String helpers, UUIDs, slugs |
| Redirects |
redirects.md |
Redirect responses |
Templates (Code Examples)
Controllers & Routes
| Template |
Purpose |
| ApiController.php.md |
Complete CRUD controller with service |
| api-routes.md |
Versioned routes with middleware |
| routing-examples.md |
Detailed routing patterns |
Validation & Resources
| Template |
Purpose |
| FormRequest.php.md |
Store/Update Form Requests |
| validation-rules.md |
All validation rules reference |
| ApiResource.php.md |
Resource with relationships |
External APIs
| Template |
Purpose |
| HttpClientService.php.md |
Reusable HTTP client service |
Quick Reference
Resource Response
return PostResource::collection($posts);
return PostResource::make($post);
Status Codes
return PostResource::make($post)->response()->setStatusCode(201);
return response()->json(null, 204);
Form Request
public function store(StorePostRequest $request): JsonResponse
{
$post = $this->service->create($request->validated());
return PostResource::make($post)->response()->setStatusCode(201);
}
Rate Limiting
Route::middleware('throttle:60,1')->group(fn () => ...);
Versioned Routes
Route::prefix('v1')->group(function () {
Route::apiResource('posts', PostController::class);
});
Pagination
return PostResource::collection(Post::paginate(15));
Feature Matrix
| Feature |
Status |
Reference |
| RESTful Controllers |
✅ |
controllers.md |
| API Resources |
✅ |
responses.md |
| Form Request Validation |
✅ |
validation.md |
| Route Versioning |
✅ |
routing.md |
| Route Model Binding |
✅ |
routing.md |
| Middleware |
✅ |
middleware.md |
| Rate Limiting |
✅ |
rate-limiting.md |
| Pagination |
✅ |
pagination.md |
| Cursor Pagination |
✅ |
pagination.md |
| HTTP Client |
✅ |
http-client.md |
| Signed URLs |
✅ |
urls.md |
| JSON Responses |
✅ |
responses.md |
Laravel 13 Notes
Attributes pour API Resources
Laravel 13 introduit #[Collects] et #[PreserveKeys] pour configurer les ResourceCollections via attributs PHP.
use Illuminate\Http\Resources\Json\ResourceCollection;
use Illuminate\Http\Resources\Attributes\Collects;
use Illuminate\Http\Resources\Attributes\PreserveKeys;
#[Collects(PostResource::class)]
#[PreserveKeys]
final class PostCollection extends ResourceCollection {}
JSON:API compliance
Pour les APIs JSON:API (sparse fieldsets, inclusion, links), voir [[laravel-jsonapi]] qui couvre ?include=, ?fields[type]=, et la pagination conforme spec.
Best Practices
DO
- Utiliser API Resources (
JsonResource) pour toute réponse JSON publique
- Versionner via URL (
/api/v1) plutôt que via header (lisible, cacheable)
- Rate-limiter par utilisateur ET par IP (
throttle:60,1 + custom limiter)
- Documenter via OpenAPI/Scribe avant de coder l'endpoint
- Préférer
cursor() pagination pour grandes listes (stable, performant)
DON'T
- Retourner directement un Model Eloquent (fuite de colonnes sensibles)
- Mélanger statuts HTTP (toujours 422 pour validation, 401 vs 403)
- Skip Form Request validation (jamais valider en controller)
- Exposer les IDs auto-increment publiquement (préférer UUID/ULID)
- Oublier
PreventRequestForgery exemption pour les webhooks externes
1---2name: laravel-api3description: Use when creating API endpoints, transforming responses with API Resources, or handling API authentication, rate limiting, or versioning.4versions:5 laravel: "13.0"6 php: "8.3"7user-invocable: true8references: references/routing.md, references/controllers.md, references/middleware.md, references/requests.md, references/responses.md, references/validation.md, references/pagination.md, references/http-client.md, references/rate-limiting.md, references/redirects.md, references/urls.md, references/strings.md9related-skills: laravel-auth, laravel-eloquent, laravel-testing10metadata:11 source: https://skillmd.com/skills/fusengine/laravel-api12---1314<objective>15Covers building RESTful APIs with Laravel: API Resources for response16transformation, Sanctum authentication, rate limiting, route versioning, Form17Request validation, pagination (offset/cursor), and consuming external APIs18via the HTTP client. For JSON:API-spec-compliant endpoints (sparse fieldsets,19inclusion, links), see laravel-jsonapi instead.20</objective>2122# Laravel API Development2324## Agent Workflow (MANDATORY)2526Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:27281. **fuse-ai-pilot:explore-codebase** - Analyze existing API patterns292. **fuse-ai-pilot:research-expert** - Verify Laravel API docs via Context7303. **mcp__context7__query-docs** - Check API Resources and Sanctum patterns3132After implementation, run **fuse-ai-pilot:sniper** for validation.3334---3536## Overview3738Build RESTful APIs with Laravel using API Resources for response transformation and Sanctum for authentication.3940| Component | Purpose |41|-----------|---------|42| **Controllers** | Handle requests, delegate to services |43| **Form Requests** | Validate input, authorize actions |44| **API Resources** | Transform models to JSON |45| **Middleware** | Auth, rate limiting, CORS |46| **Routes** | Versioned endpoints with groups |47| **Pagination** | Offset/cursor pagination |48| **HTTP Client** | Consume external APIs |4950---5152## Critical Rules53541. **Always use API Resources** - Never return Eloquent models directly552. **Versioned routes** - Prefix with `/v1/`, `/v2/`563. **Validate all input** - Use Form Requests, not inline validation574. **Rate limiting** - Configure per-route limits585. **Consistent responses** - Same structure, proper status codes596. **Use services** - Keep controllers thin607. **Eager load** - Prevent N+1 with `with()` before pagination6162---6364## Reference Guide6566### Core Concepts6768| Topic | Reference | When to consult |69|-------|-----------|-----------------|70| **Routing** | [routing.md](references/routing.md) | Defining versioned API routes |71| **Controllers** | [controllers.md](references/controllers.md) | Controller patterns, resource methods |72| **Middleware** | [middleware.md](references/middleware.md) | Route protection, request filtering |73| **Validation** | [validation.md](references/validation.md) | Form Requests, validation rules |7475### Request/Response7677| Topic | Reference | When to consult |78|-------|-----------|-----------------|79| **Requests** | [requests.md](references/requests.md) | Accessing input, files, headers |80| **Responses** | [responses.md](references/responses.md) | API Resources, status codes |81| **Pagination** | [pagination.md](references/pagination.md) | Offset/cursor pagination |8283### Advanced8485| Topic | Reference | When to consult |86|-------|-----------|-----------------|87| **Rate Limiting** | [rate-limiting.md](references/rate-limiting.md) | Throttle configuration |88| **HTTP Client** | [http-client.md](references/http-client.md) | Consuming external APIs |89| **URLs** | [urls.md](references/urls.md) | URL generation, signed URLs |90| **Strings** | [strings.md](references/strings.md) | String helpers, UUIDs, slugs |91| **Redirects** | [redirects.md](references/redirects.md) | Redirect responses |9293---9495### Templates (Code Examples)9697#### Controllers & Routes9899| Template | Purpose |100|----------|---------|101| [ApiController.php.md](references/templates/ApiController.php.md) | Complete CRUD controller with service |102| [api-routes.md](references/templates/api-routes.md) | Versioned routes with middleware |103| [routing-examples.md](references/templates/routing-examples.md) | Detailed routing patterns |104105#### Validation & Resources106107| Template | Purpose |108|----------|---------|109| [FormRequest.php.md](references/templates/FormRequest.php.md) | Store/Update Form Requests |110| [validation-rules.md](references/templates/validation-rules.md) | All validation rules reference |111| [ApiResource.php.md](references/templates/ApiResource.php.md) | Resource with relationships |112113#### External APIs114115| Template | Purpose |116|----------|---------|117| [HttpClientService.php.md](references/templates/HttpClientService.php.md) | Reusable HTTP client service |118119---120121## Quick Reference122123### Resource Response124125```php126return PostResource::collection($posts);127return PostResource::make($post);128```129130### Status Codes131132```php133return PostResource::make($post)->response()->setStatusCode(201);134return response()->json(null, 204);135```136137### Form Request138139```php140public function store(StorePostRequest $request): JsonResponse141{142 $post = $this->service->create($request->validated());143 return PostResource::make($post)->response()->setStatusCode(201);144}145```146147### Rate Limiting148149```php150Route::middleware('throttle:60,1')->group(fn () => ...);151```152153### Versioned Routes154155```php156Route::prefix('v1')->group(function () {157 Route::apiResource('posts', PostController::class);158});159```160161### Pagination162163```php164return PostResource::collection(Post::paginate(15));165```166167---168169## Feature Matrix170171| Feature | Status | Reference |172|---------|--------|-----------|173| RESTful Controllers | ✅ | controllers.md |174| API Resources | ✅ | responses.md |175| Form Request Validation | ✅ | validation.md |176| Route Versioning | ✅ | routing.md |177| Route Model Binding | ✅ | routing.md |178| Middleware | ✅ | middleware.md |179| Rate Limiting | ✅ | rate-limiting.md |180| Pagination | ✅ | pagination.md |181| Cursor Pagination | ✅ | pagination.md |182| HTTP Client | ✅ | http-client.md |183| Signed URLs | ✅ | urls.md |184| JSON Responses | ✅ | responses.md |185186---187188## Laravel 13 Notes189190### Attributes pour API Resources191Laravel 13 introduit `#[Collects]` et `#[PreserveKeys]` pour configurer les ResourceCollections via attributs PHP.192193```php194use Illuminate\Http\Resources\Json\ResourceCollection;195use Illuminate\Http\Resources\Attributes\Collects;196use Illuminate\Http\Resources\Attributes\PreserveKeys;197198#[Collects(PostResource::class)]199#[PreserveKeys]200final class PostCollection extends ResourceCollection {}201```202203### JSON:API compliance204Pour les APIs JSON:API (sparse fieldsets, inclusion, links), voir [[laravel-jsonapi]] qui couvre `?include=`, `?fields[type]=`, et la pagination conforme spec.205206## Best Practices207208### DO209- Utiliser API Resources (`JsonResource`) pour toute réponse JSON publique210- Versionner via URL (`/api/v1`) plutôt que via header (lisible, cacheable)211- Rate-limiter par utilisateur ET par IP (`throttle:60,1` + custom limiter)212- Documenter via OpenAPI/Scribe avant de coder l'endpoint213- Préférer `cursor()` pagination pour grandes listes (stable, performant)214215### DON'T216- Retourner directement un Model Eloquent (fuite de colonnes sensibles)217- Mélanger statuts HTTP (toujours 422 pour validation, 401 vs 403)218- Skip Form Request validation (jamais valider en controller)219- Exposer les IDs auto-increment publiquement (préférer UUID/ULID)220- Oublier `PreventRequestForgery` exemption pour les webhooks externes