laravel-api

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.

Laravel API Development

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

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	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 for API Resources

Laravel 13 introduces #[Collects] and #[PreserveKeys] to configure ResourceCollections via PHP attributes.

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

For JSON:API APIs (sparse fieldsets, includes, links), see [[laravel-jsonapi]], which covers ?include=, ?fields[type]=, and spec-compliant pagination.

Best Practices

DO

• Use API Resources (JsonResource) for every public JSON response
• Version via URL (/api/v1) rather than via header (readable, cacheable)
• Rate-limit per user AND per IP (throttle:60,1 + custom limiter)
• Document via OpenAPI/Scribe before coding the endpoint
• Prefer cursor() pagination for large lists (stable, performant)

DON'T

• Return an Eloquent Model directly (leaks sensitive columns)
• Mix up HTTP statuses (always 422 for validation, 401 vs 403)
• Skip Form Request validation (never validate in the controller)
• Expose auto-increment IDs publicly (prefer UUID/ULID)
• Forget the PreventRequestForgery exemption for external webhooks