laravel-api

---
name: laravel-api
description: Use when creating API endpoints, transforming responses with API Resources, or handling API authentication, rate limiting, or versioning.
license: MIT
---

<objective>
Covers building RESTful APIs with Laravel: API Resources for response
transformation, Sanctum authentication, rate limiting, route versioning, Form
Request validation, pagination (offset/cursor), and consuming external APIs
via the HTTP client. For JSON:API-spec-compliant endpoints (sparse fieldsets,
inclusion, links), see laravel-jsonapi instead.
</objective>

# Laravel API Development

## Agent Workflow (MANDATORY)

Before ANY implementation, use `TeamCreate` to spawn 3 agents:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing API patterns
2. **fuse-ai-pilot:research-expert** - Verify Laravel API docs via Context7
3. **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

1. **Always use API Resources** - Never return Eloquent models directly
2. **Versioned routes** - Prefix with `/v1/`, `/v2/`
3. **Validate all input** - Use Form Requests, not inline validation
4. **Rate limiting** - Configure per-route limits
5. **Consistent responses** - Same structure, proper status codes
6. **Use services** - Keep controllers thin
7. **Eager load** - Prevent N+1 with `with()` before pagination

---

## Reference Guide

### Core Concepts

| Topic | Reference | When to consult |
|-------|-----------|-----------------|
| **Routing** | [routing.md](references/routing.md) | Defining versioned API routes |
| **Controllers** | [controllers.md](references/controllers.md) | Controller patterns, resource methods |
| **Middleware** | [middleware.md](references/middleware.md) | Route protection, request filtering |
| **Validation** | [validation.md](references/validation.md) | Form Requests, validation rules |

### Request/Response

| Topic | Reference | When to consult |
|-------|-----------|-----------------|
| **Requests** | [requests.md](references/requests.md) | Accessing input, files, headers |
| **Responses** | [responses.md](references/responses.md) | API Resources, status codes |
| **Pagination** | [pagination.md](references/pagination.md) | Offset/cursor pagination |

### Advanced

| Topic | Reference | When to consult |
|-------|-----------|-----------------|
| **Rate Limiting** | [rate-limiting.md](references/rate-limiting.md) | Throttle configuration |
| **HTTP Client** | [http-client.md](references/http-client.md) | Consuming external APIs |
| **URLs** | [urls.md](references/urls.md) | URL generation, signed URLs |
| **Strings** | [strings.md](references/strings.md) | String helpers, UUIDs, slugs |
| **Redirects** | [redirects.md](references/redirects.md) | Redirect responses |

---

### Templates (Code Examples)

#### Controllers & Routes

| Template | Purpose |
|----------|---------|
| [ApiController.php.md](references/templates/ApiController.php.md) | Complete CRUD controller with service |
| [api-routes.md](references/templates/api-routes.md) | Versioned routes with middleware |
| [routing-examples.md](references/templates/routing-examples.md) | Detailed routing patterns |

#### Validation & Resources

| Template | Purpose |
|----------|---------|
| [FormRequest.php.md](references/templates/FormRequest.php.md) | Store/Update Form Requests |
| [validation-rules.md](references/templates/validation-rules.md) | All validation rules reference |
| [ApiResource.php.md](references/templates/ApiResource.php.md) | Resource with relationships |

#### External APIs

| Template | Purpose |
|----------|---------|
| [HttpClientService.php.md](references/templates/HttpClientService.php.md) | Reusable HTTP client service |

---

## Quick Reference

### Resource Response

```php
return PostResource::collection($posts);
return PostResource::make($post);
```

### Status Codes

```php
return PostResource::make($post)->response()->setStatusCode(201);
return response()->json(null, 204);
```

### Form Request

```php
public function store(StorePostRequest $request): JsonResponse
{
    $post = $this->service->create($request->validated());
    return PostResource::make($post)->response()->setStatusCode(201);
}
```

### Rate Limiting

```php
Route::middleware('throttle:60,1')->group(fn () => ...);
```

### Versioned Routes

```php
Route::prefix('v1')->group(function () {
    Route::apiResource('posts', PostController::class);
});
```

### Pagination

```php
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.

```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