laravel-api-kit/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Laravel API Kit is an API-only Laravel 12 starter kit following the 2024-2025 REST API ecosystem best practices. No frontend (Blade, Vite, Vue, React) - purely headless API for mobile apps, SPAs, or microservices.

Tech Stack

• PHP: 8.3+
• Laravel: 12.x
• Authentication: Laravel Sanctum (token-based)
• API Versioning: grazulex/laravel-apiroute
• Query Building: spatie/laravel-query-builder
• Data Transformation: spatie/laravel-data + Laravel API Resources
• Documentation: dedoc/scramble (zero-annotation OpenAPI 3.1)
• Testing: Pest PHP 3.x

Key Commands

All commands run via Docker:

# Run tests
docker compose run --rm app ./vendor/bin/pest

# Run specific test file
docker compose run --rm app ./vendor/bin/pest tests/Feature/Api/V1/AuthTest.php

# Code formatting
docker compose run --rm app ./vendor/bin/pint

# List routes
docker compose run --rm app php artisan route:list

# Clear caches
docker compose run --rm app php artisan config:clear
docker compose run --rm app php artisan cache:clear

# Run migrations
docker compose run --rm app php artisan migrate

# Generate OpenAPI docs
docker compose run --rm app php artisan scramble:export

Architecture

app/
├── Actions/              # Single-purpose action classes
├── DTOs/                 # Data Transfer Objects (spatie/laravel-data)
├── Http/
│   ├── Controllers/
│   │   └── Api/
│   │       ├── ApiController.php   # Base controller with ApiResponse trait
│   │       └── V1/                 # Versioned controllers
│   ├── Requests/Api/V1/            # Form Requests per version
│   └── Resources/                  # API Resources
├── Models/
├── Services/             # Business logic services
└── Traits/
    └── ApiResponse.php   # Standardized JSON responses

routes/
├── api.php              # API routes with grazulex/laravel-apiroute versioning

config/
├── apiroute.php         # API versioning config (URI prefix set to empty for Laravel 12)
├── sanctum.php          # Token authentication config
├── scramble.php         # OpenAPI documentation config
└── cors.php             # CORS settings with API headers exposed

API Endpoints

Base URL: /api/v1

Method	Endpoint	Auth Required	Description
POST	/register	No	Register new user
POST	/login	No	Get auth token
POST	/logout	Yes	Revoke current token
GET	/me	Yes	Get current user

Response Format

All responses use the ApiResponse trait format:

{
  "success": true,
  "message": "Success message",
  "data": { ... }
}

Error responses:

{
  "success": false,
  "message": "Error message",
  "errors": { ... }
}

Adding New API Version

1. Create controller in app/Http/Controllers/Api/V2/
2. Create requests in app/Http/Requests/Api/V2/
3. Add routes in routes/api.php:

ApiRoute::version('v2', function () {
    // V2 routes
})->current();

// Mark V1 as deprecated
ApiRoute::version('v1', function () {
    // V1 routes
})->deprecated('2025-06-01')->sunset('2025-12-01');

Testing

Tests use Pest PHP with Laravel HTTP testing:

it('registers a new user', function () {
    $response = $this->postJson('/api/v1/register', [
        'name' => 'Test User',
        'email' => 'test@example.com',
        'password' => 'password123',
        'password_confirmation' => 'password123',
    ]);

    $response->assertStatus(201)
        ->assertJson(['success' => true]);
});

Rate Limiting

Configured in AppServiceProvider:

• api: 60 req/min (default)
• auth: 5 req/min (login/register protection)
• authenticated: 120 req/min (logged-in users)

Documentation

API documentation auto-generated by Scramble:

• UI: /docs/api
• JSON: /docs/api.json

No annotations needed - Scramble analyzes Form Requests and API Resources.