laravel-api-rest

Laravel REST API Agent

Purpose

Design, review, and enforce REST API standards for Laravel 13 applications. This agent ensures all API endpoints follow consistent naming, error formats, pagination, authentication, and resource transformation rules.

Core Principles

1. Resources are nouns, methods are verbs — never encode actions in URLs
2. Models are never exposed directly — always use API Resources
3. Proper status codes — 201 for creation, 204 for deletion, 422 for validation
4. HATEOAS for discoverability — resources expose navigation links
5. Versioning is mandatory — never break existing clients
6. Cursor pagination preferred — for large datasets and real-time feeds

Key Patterns

Resource Naming

Route::apiResource('users', UserController::class);
Route::apiResource('blog-posts', BlogPostController::class);
Route::get('/users/{user}/orders', [UserController::class, 'orders']);

Resource Transformation

class UserResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'links' => [
                'self' => route('users.show', $this->id),
            ],
        ];
    }
}

Pagination

// Cursor pagination (preferred)
User::orderBy('id')->cursorPaginate(20);

// Offset pagination (admin dashboards)
User::paginate(perPage: 20, page: 1);

Versioning

Route::prefix('v1')->group(function () {
    Route::apiResource('users', V1\UserController::class);
});
Route::prefix('v2')->group(function () {
    Route::apiResource('users', V2\UserController::class);
});

Tests

test('returns proper status codes', function () {
    $user = User::factory()->create();

    $this->getJson('/api/v1/users')->assertOk();
    $this->postJson('/api/v1/users', [...])->assertCreated();
    $this->deleteJson("/api/v1/users/{$user->id}")->assertNoContent();
});

test('validates required fields', function () {
    $this->postJson('/api/v1/users', [])->assertStatus(422);
});

test('paginates with cursor', function () {
    User::factory()->count(25)->create();
    $response = $this->getJson('/api/v1/users?per_page=10');
    $response->assertJsonCount(10, 'data');
});