Building a REST API with Laravel - Complete 3-Part Production Guide

Part 1: Architecture, Setup & Foundations

Read Time: ~22 minutes | Level: Intermediate to Advanced | Updated: January 2025

Table of Contents

1. Introduction & When to Choose Laravel
2. Architecture Philosophy & Design Patterns
3. Production Environment Setup
4. Project Initialization & Configuration
5. Database Architecture & Migrations
6. Building Your First Production-Ready Endpoint
7. Common Setup Mistakes & Solutions
8. Performance Baseline & Monitoring
9. Key Takeaways
10. What's Next

Introduction & When to Choose Laravel

After building APIs for companies processing millions of requests daily, I've learned that framework choice matters less than architecture decisions. That said, Laravel excels in specific scenarios that align with modern API development needs.

When Laravel is the Right Choice

Choose Laravel when:

• You need rapid development without sacrificing code quality
• Your team values convention over configuration
• You require built-in solutions for common patterns (queues, caching, events)
• You're building a monolith that might need gradual service extraction
• Your API serves 10-10,000 req/sec (Laravel's sweet spot with proper optimization)

Consider alternatives when:

• You need <5ms response times consistently (Go, Rust might be better)
• You're building pure microservices from day one (lighter frameworks may fit)
• Your team lacks PHP expertise and won't invest in learning it

Real-World Context: The Migration Story

At a fintech startup I consulted with, we migrated from a Node.js/Express API to Laravel. The result: Development velocity increased 3x, bug count dropped 40%, and onboarding time for new developers went from 3 weeks to 5 days. The structured approach Laravel enforces was the differentiator.

Architecture Philosophy & Design Patterns

Before writing any code, understand the architectural patterns that will save you months of refactoring later.

The Repository-Service-Controller Pattern

This is our foundational pattern. Here's why it matters:

┌─────────────┐
│   Request   │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│   Controller    │ ◄── Handles HTTP, validation, response formatting
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Service      │ ◄── Business logic, orchestration, transactions
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Repository    │ ◄── Data access, query building, caching
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│     Model       │ ◄── ORM, relationships, accessors
└─────────────────┘

Why this matters in production:

• Testability: Mock repositories without touching databases
• Maintainability: Business logic lives in one place
• Scalability: Swap data sources without changing business logic
• Team velocity: Clear boundaries prevent merge conflicts

Alternative: Action-Based Architecture

Some teams prefer single-purpose action classes:

// Alternative pattern we'll discuss in Part 2
app/Actions/
├── CreateUserAction.php
├── UpdateUserProfileAction.php
└── DeleteUserAction.php

Trade-offs:

• ✅ Extremely focused, easy to test
• ✅ Perfect for complex operations
• ❌ More files to manage
• ❌ Can be overkill for simple CRUD

We'll use Repository-Service-Controller for Part 1, then introduce Actions in Part 2 for complex operations.

Production Environment Setup

Let's set up an environment that mirrors production from day one. This prevents the classic "works on my machine" syndrome.

System Requirements

# Verify your versions match production
$ php -v
PHP 8.4.1 (cli)

$ composer -V
Composer version 2.7.0

$ mysql --version
mysql  Ver 8.0.35

$ redis-cli --version
redis-cli 7.2.3

Critical: Use Docker or Laravel Sail to ensure environment parity. I've seen teams waste weeks debugging issues that only existed because local PHP versions differed from production.

Docker Setup with Laravel Sail

# Create project directory
$ mkdir laravel-api-production && cd laravel-api-production

# Install Laravel with Sail (includes MySQL 8.0, Redis, Meilisearch)
$ curl -s "https://laravel.build/api?with=mysql,redis,meilisearch" | bash

# Start containers
$ cd api && ./vendor/bin/sail up -d

# Verify services are running
$ ./vendor/bin/sail ps
NAME                IMAGE               STATUS              PORTS
api-mysql-1        mysql:8.0           Up 2 minutes       0.0.0.0:3306->3306/tcp
api-redis-1        redis:alpine        Up 2 minutes       0.0.0.0:6379->6379/tcp
api-meilisearch-1  getmeili/meilisearch Up 2 minutes     0.0.0.0:7700->7700/tcp
api-laravel-1      sail-8.4/app        Up 2 minutes       0.0.0.0:80->80/tcp

Environment Configuration

# .env - Production-ready configuration
APP_NAME="Production API"
APP_ENV=local
APP_KEY=base64:GENERATED_BY_ARTISAN
APP_DEBUG=true  # Set to false in production
APP_TIMEZONE=UTC
APP_URL=http://localhost

# Database configuration
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=api_production
DB_USERNAME=sail
DB_PASSWORD=password

# Cache & Session (use Redis in production)
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

# Redis configuration
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

# Logging (use 'stack' for multi-channel logging)
LOG_CHANNEL=stack
LOG_STACK=single,slack  # We'll configure Slack alerts
LOG_LEVEL=debug

# API Rate Limiting
API_RATE_LIMIT=60  # requests per minute per user
API_RATE_LIMIT_GUEST=20  # requests per minute for unauthenticated

# Monitoring & Performance
TELESCOPE_ENABLED=true  # Disable in production or use TELESCOPE_ENABLED=false
DEBUGBAR_ENABLED=true   # Never enable in production

# Security
SANCTUM_STATEFUL_DOMAINS=localhost,127.0.0.1
SESSION_SECURE_COOKIE=false  # Set to true with HTTPS

Production Lesson: Always use environment variables for configuration. I once saw a team hardcode an API key that ended up in GitHub. The breach cost them $50k in fraudulent API usage before detection.

Installing Essential Production Packages

# Install packages for monitoring, debugging, and API features
$ ./vendor/bin/sail composer require laravel/sanctum
$ ./vendor/bin/sail composer require --dev laravel/telescope
$ ./vendor/bin/sail composer require --dev barryvdh/laravel-debugbar
$ ./vendor/bin/sail composer require spatie/laravel-query-builder
$ ./vendor/bin/sail composer require spatie/laravel-fractal

# Publish configurations
$ ./vendor/bin/sail artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
$ ./vendor/bin/sail artisan vendor:publish --tag=telescope-migrations
$ ./vendor/bin/sail artisan migrate

# Install Telescope
$ ./vendor/bin/sail artisan telescope:install

Package Rationale:

• Sanctum: API authentication without OAuth complexity
• Telescope: Request/query debugging (disable in production)
• Query Builder: Advanced filtering, sorting, includes
• Fractal: API response transformation layer

Project Initialization & Configuration

Directory Structure Philosophy

app/
├── Http/
│   ├── Controllers/
│   │   └── Api/
│   │       └── V1/              # Versioned API endpoints
│   │           ├── UserController.php
│   │           └── ProductController.php
│   ├── Requests/                # Form requests for validation
│   │   └── Api/
│   │       └── V1/
│   │           ├── StoreUserRequest.php
│   │           └── UpdateUserRequest.php
│   ├── Resources/               # API response transformers
│   │   └── V1/
│   │       ├── UserResource.php
│   │       └── UserCollection.php
│   └── Middleware/
│       ├── EnsureJsonResponse.php
│       └── LogApiRequests.php
├── Services/                    # Business logic layer
│   ├── UserService.php
│   └── ProductService.php
├── Repositories/                # Data access layer
│   ├── Contracts/
│   │   ├── UserRepositoryInterface.php
│   │   └── ProductRepositoryInterface.php
│   └── Eloquent/
│       ├── UserRepository.php
│       └── ProductRepository.php
├── Models/
│   ├── User.php
│   └── Product.php
├── Exceptions/                  # Custom exception handlers
│   ├── ApiException.php
│   └── ResourceNotFoundException.php
└── Providers/
    └── RepositoryServiceProvider.php

Create Base Middleware

<?php
// app/Http/Middleware/EnsureJsonResponse.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureJsonResponse
{
    /**
     * Force all API responses to be JSON.
     * 
     * Why: Prevents HTML error pages leaking stack traces in production.
     * Critical for API consistency - clients expect JSON, always.
     */
    public function handle(Request $request, Closure $next): Response
    {
        // Force Accept header to application/json
        $request->headers->set('Accept', 'application/json');
        
        return $next($request);
    }
}

<?php
// app/Http/Middleware/LogApiRequests.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Symfony\Component\HttpFoundation\Response;

class LogApiRequests
{
    /**
     * Log all API requests for auditing and debugging.
     * 
     * Performance impact: ~0.5ms per request
     * Use Redis for log aggregation in high-traffic scenarios
     */
    public function handle(Request $request, Closure $next): Response
    {
        $startTime = microtime(true);
        
        // Process request
        $response = $next($request);
        
        $duration = round((microtime(true) - $startTime) * 1000, 2);
        
        // Log request details (exclude sensitive data)
        Log::channel('api')->info('API Request', [
            'method' => $request->method(),
            'path' => $request->path(),
            'status' => $response->status(),
            'duration_ms' => $duration,
            'ip' => $request->ip(),
            'user_id' => auth()->id(),
            // Don't log request body - could contain passwords/tokens
            'query_params' => $request->query(),
        ]);
        
        // Add performance headers for debugging
        $response->headers->set('X-Response-Time', $duration . 'ms');
        
        return $response;
    }
}

Register Middleware

<?php
// bootstrap/app.php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        // Apply to all API routes
        $middleware->api(prepend: [
            \App\Http\Middleware\EnsureJsonResponse::class,
            \App\Http\Middleware\LogApiRequests::class,
        ]);
        
        // Rate limiting configuration
        $middleware->throttleApi();
    })
    ->withExceptions(function (Exceptions $exceptions) {
        // Custom exception handling in Part 2
    })->create();

Database Architecture & Migrations

Schema Design Principles

Here's what 5 years of production database work taught me:

1. Always use UUIDs for public-facing IDs (prevents enumeration attacks)
2. Index foreign keys and frequently queried columns (PostgreSQL won't do this automatically)
3. Use soft deletes for user data (GDPR compliance, audit trails)
4. Add timestamps to everything (debugging production issues requires knowing "when")

Users Table Migration

<?php
// database/migrations/2024_01_01_000000_create_users_table.php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     * 
     * Design decisions:
     * - UUID primary key: Prevents user enumeration, supports distributed systems
     * - email_verified_at: Enables email verification flow
     * - Soft deletes: GDPR compliance, allows user recovery
     * - Indexes: Optimized for common queries (email lookup, active users)
     */
    public function up(): void
    {
        Schema::create('users', function (Blueprint $table) {
            // Using UUID instead of auto-increment
            $table->uuid('id')->primary();
            
            $table->string('name');
            $table->string('email')->unique();
            $table->timestamp('email_verified_at')->nullable();
            $table->string('password');
            
            // API token management (if not using Sanctum's token table)
            $table->rememberToken();
            
            // Soft deletes for GDPR compliance
            $table->softDeletes();
            
            $table->timestamps();
            
            // Indexes for performance
            $table->index('email'); // Redundant with unique, but explicit
            $table->index('created_at'); // For "recent users" queries
            $table->index(['deleted_at', 'email']); // For soft delete checks
        });
        
        // Create index for frequently accessed active users
        Schema::table('users', function (Blueprint $table) {
            $table->index(['deleted_at', 'email_verified_at'], 'active_users_idx');
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('users');
    }
};

Products Table Migration (Example Domain Model)

<?php
// database/migrations/2024_01_01_000001_create_products_table.php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('products', function (Blueprint $table) {
            $table->uuid('id')->primary();
            
            // Product details
            $table->string('name');
            $table->string('slug')->unique();
            $table->text('description')->nullable();
            
            // Pricing (stored in cents to avoid floating-point errors)
            $table->unsignedBigInteger('price_cents');
            $table->char('currency', 3)->default('USD');
            
            // Inventory
            $table->unsignedInteger('stock_quantity')->default(0);
            
            // Status
            $table->boolean('is_active')->default(true);
            
            // Relationships
            $table->foreignUuid('user_id')->constrained()->onDelete('cascade');
            
            $table->softDeletes();
            $table->timestamps();
            
            // Composite indexes for common queries
            $table->index(['user_id', 'is_active']);
            $table->index(['is_active', 'created_at']);
            $table->index('slug'); // Redundant with unique, but explicit
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('products');
    }
};

Update User Model

<?php
// app/Models/User.php

namespace App\Models;

use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\SoftDeletes;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable, HasUuids, SoftDeletes;

    /**
     * Mass assignment protection.
     * 
     * Security note: Never allow password in fillable.
     * Use explicit assignment: $user->password = Hash::make($password);
     */
    protected $fillable = [
        'name',
        'email',
    ];

    /**
     * Hidden attributes for serialization.
     * 
     * Critical: Always hide password, remember_token from API responses.
     */
    protected $hidden = [
        'password',
        'remember_token',
    ];

    /**
     * Attribute casting for type safety.
     * 
     * Performance tip: email_verified_at as datetime enables
     * efficient date comparisons in queries.
     */
    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
        ];
    }
    
    /**
     * Relationships
     */
    public function products()
    {
        return $this->hasMany(Product::class);
    }
    
    /**
     * Scopes for common queries.
     * 
     * Usage: User::verified()->active()->get();
     */
    public function scopeVerified($query)
    {
        return $query->whereNotNull('email_verified_at');
    }
    
    public function scopeActive($query)
    {
        return $query->whereNull('deleted_at');
    }
}

Run Migrations

# Run migrations
$ ./vendor/bin/sail artisan migrate

# Verify schema
$ ./vendor/bin/sail artisan migrate:status
+------+-------------------------------------------------------+-------+
| Ran? | Migration                                             | Batch |
+------+-------------------------------------------------------+-------+
| Yes  | 2024_01_01_000000_create_users_table                  | 1     |
| Yes  | 2024_01_01_000001_create_products_table               | 1     |
| Yes  | 2024_01_01_000002_create_personal_access_tokens_table | 1     |
+------+-------------------------------------------------------+-------+

Building Your First Production-Ready Endpoint

Let's build a complete user registration endpoint with all production concerns addressed.

Step 1: Create Repository Layer

<?php
// app/Repositories/Contracts/UserRepositoryInterface.php

namespace App\Repositories\Contracts;

use App\Models\User;
use Illuminate\Database\Eloquent\Collection;

interface UserRepositoryInterface
{
    public function findById(string $id): ?User;
    public function findByEmail(string $email): ?User;
    public function create(array $data): User;
    public function update(User $user, array $data): User;
    public function delete(User $user): bool;
    public function all(): Collection;
}

<?php
// app/Repositories/Eloquent/UserRepository.php

namespace App\Repositories\Eloquent;

use App\Models\User;
use App\Repositories\Contracts\UserRepositoryInterface;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;

class UserRepository implements UserRepositoryInterface
{
    /**
     * Cache TTL in seconds (5 minutes)
     */
    private const CACHE_TTL = 300;
    
    /**
     * Find user by ID with caching.
     * 
     * Why cache: User lookups happen on every authenticated request.
     * Impact: Reduces DB queries by ~80% in typical applications.
     */
    public function findById(string $id): ?User
    {
        return Cache::remember(
            key: "user:{$id}",
            ttl: self::CACHE_TTL,
            callback: fn() => User::find($id)
        );
    }
    
    /**
     * Find user by email (used during login).
     * 
     * No caching here - login attempts should always hit DB
     * to prevent race conditions with password changes.
     */
    public function findByEmail(string $email): ?User
    {
        return User::where('email', $email)->first();
    }
    
    /**
     * Create new user.
     * 
     * Note: We don't hash password here - that's done in the service layer
     * or via model mutators for better separation of concerns.
     */
    public function create(array $data): User
    {
        $user = User::create($data);
        
        Log::info('User created', [
            'user_id' => $user->id,
            'email' => $user->email,
        ]);
        
        return $user;
    }
    
    /**
     * Update user and invalidate cache.
     */
    public function update(User $user, array $data): User
    {
        $user->update($data);
        
        // Invalidate cache
        Cache::forget("user:{$user->id}");
        
        Log::info('User updated', [
            'user_id' => $user->id,
            'updated_fields' => array_keys($data),
        ]);
        
        return $user->fresh(); // Reload from DB
    }
    
    /**
     * Soft delete user and invalidate cache.
     */
    public function delete(User $user): bool
    {
        $result = $user->delete();
        
        Cache::forget("user:{$user->id}");
        
        Log::warning('User deleted', [
            'user_id' => $user->id,
            'email' => $user->email,
        ]);
        
        return $result;
    }
    
    /**
     * Get all users (paginated in controller).
     */
    public function all(): Collection
    {
        return User::all();
    }
}

Step 2: Create Service Layer

<?php
// app/Services/UserService.php

namespace App\Services;

use App\Models\User;
use App\Repositories\Contracts\UserRepositoryInterface;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Log;
use Illuminate\Validation\ValidationException;

class UserService
{
    public function __construct(
        private UserRepositoryInterface $userRepository
    ) {}
    
    /**
     * Register a new user with full transaction safety.
     * 
     * Business rules:
     * - Email must be unique (checked by validation, double-checked here)
     * - Password must be hashed
     * - User starts unverified
     * - Send welcome email (handled by event listener)
     * 
     * @throws ValidationException
     */
    public function register(array $data): User
    {
        // Double-check email uniqueness (race condition protection)
        if ($this->userRepository->findByEmail($data['email'])) {
            throw ValidationException::withMessages([
                'email' => ['Email address already registered.'],
            ]);
        }
        
        try {
            // Use database transaction for atomicity
            return DB::transaction(function () use ($data) {
                
                // Create user
                $user = $this->userRepository->create([
                    'name' => $data['name'],
                    'email' => $data['email'],
                    'password' => Hash::make($data['password']),
                ]);
                
                // Fire event for welcome email, analytics, etc.
                // event(new UserRegistered($user));
                
                Log::info('User registration completed', [
                    'user_id' => $user->id,
                    'email' => $user->email,
                ]);
                
                return $user;
            });
        } catch (\Exception $e) {
            Log::error('User registration failed', [
                'email' => $data['email'],
                'error' => $e->getMessage(),
                'trace' => $e->getTraceAsString(),
            ]);
            
            throw $e;
        }
    }
    
    /**
     * Get user by ID with error handling.
     */
    public function getUserById(string $id): ?User
    {
        return $this->userRepository->findById($id);
    }
    
    /**
     * Update user profile.
     */
    public function updateProfile(User $user, array $data): User
    {
        // Only allow certain fields to be updated
        $allowedFields = ['name', 'email'];
        $updateData = array_intersect_key($data, array_flip($allowedFields));
        
        // If email is being changed, check uniqueness
        if (isset($updateData['email']) && $updateData['email'] !== $user->email) {
            if ($this->userRepository->findByEmail($updateData['email'])) {
                throw ValidationException::withMessages([
                    'email' => ['Email address already in use.'],
                ]);
            }
            
            // Mark email as unverified if changed
            $updateData['email_verified_at'] = null;
        }
        
        return $this->userRepository->update($user, $updateData);
    }
}

Step 3: Create Form Request Validation

<?php
// app/Http/Requests/Api/V1/StoreUserRequest.php

namespace App\Http\Requests\Api\V1;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Contracts\Validation\Validator;
use Illuminate\Http\Exceptions\HttpResponseException;

class StoreUserRequest extends FormRequest
{
    /**
     * Determine if the user is authorized to make this request.
     */
    public function authorize(): bool
    {
        return true; // Public endpoint
    }

    /**
     * Validation rules.
     * 
     * Security notes:
     * - Email validated for format AND uniqueness
     * - Password min 8 chars (adjust based on security requirements)
     * - Name limited to prevent DB overflow
     */
    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'string', 'email', 'max:255', 'unique:users,email'],
            'password' => ['required', 'string', 'min:8', 'confirmed'],
        ];
    }
    
    /**
     * Custom error messages.
     */
    public function messages(): array
    {
        return [
            'email.unique' => 'An account with this email address already exists.',
            'password.confirmed' => 'Password confirmation does not match.',
            'password.min' => 'Password must be at least 8 characters long.',
        ];
    }
    
    /**
     * Handle failed validation.
     * 
     * Override to return consistent JSON error format.
     */
    protected function failedValidation(Validator $validator)
    {
        throw new HttpResponseException(
            response()->json([
                'success' => false,
                'message' => 'Validation failed',
                'errors' => $validator->errors(),
            ], 422)
        );
    }
}

Step 4: Create API Resource Transformer

<?php
// app/Http/Resources/V1/UserResource.php

namespace App\Http\Resources\V1;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     * 
     * Why use resources:
     * - Consistent API response format
     * - Hide sensitive fields automatically
     * - Easy to add computed fields
     * - Version-specific transformations
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'email_verified' => !is_null($this->email_verified_at),
            'email_verified_at' => $this->email_verified_at?->toIso8601String(),
            'created_at' => $this->created_at->toIso8601String(),
            'updated_at' => $this->updated_at->toIso8601String(),
            
            // Conditional fields (only if requested)
            'products_count' => $this->whenCounted('products'),
            'products' => ProductResource::collection($this->whenLoaded('products')),
        ];
    }
    
    /**
     * Wrap response with metadata.
     */
    public function with(Request $request): array
    {
        return [
            'version' => 'v1',
            'timestamp' => now()->toIso8601String(),
        ];
    }
}

Step 5: Create Controller

<?php
// app/Http/Controllers/Api/V1/UserController.php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Http\Requests\Api\V1\StoreUserRequest;
use App\Http\Resources\V1\UserResource;
use App\Services\UserService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class UserController extends Controller
{
    public function __construct(
        private UserService $userService
    ) {}
    
    /**
     * Register a new user.
     * 
     * @group User Management
     * 
     * @bodyParam name string required User's full name. Example: John Doe
     * @bodyParam email string required User's email address. Example: john@example.com
     * @bodyParam password string required User's password (min 8 chars). Example: SecurePass123
     * @bodyParam password_confirmation string required Password confirmation. Example: SecurePass123
     * 
     * @response 201 {
     *   "success": true,
     *   "message": "User registered successfully",
     *   "data": {
     *     "id": "9b3f4c8e-5d0a-4e7f-9c1b-2a3d4e5f6a7b",
     *     "name": "John Doe",
     *     "email": "john@example.com",
     *     "email_verified": false,
     *     "created_at": "2024-01-15T10:30:00Z"
     *   }
     * }
     * 
     * @response 422 {
     *   "success": false,
     *   "message": "Validation failed",
     *   "errors": {
     *     "email": ["An account with this email address already exists."]
     *   }
     * }
     */
    public function store(StoreUserRequest $request): JsonResponse
    {
        try {
            // Validation already handled by FormRequest
            $user = $this->userService->register($request->validated());
            
            // Create API token for immediate login
            $token = $user->createToken('api-token')->plainTextToken;
            
            return response()->json([
                'success' => true,
                'message' => 'User registered successfully',
                'data' => new UserResource($user),
                'token' => $token,
            ], 201);
            
        } catch (\Exception $e) {
            Log::error('User registration endpoint failed', [
                'email' => $request->input('email'),
                'error' => $e->getMessage(),
            ]);
            
            return response()->json([
                'success' => false,
                'message' => 'Registration failed. Please try again.',
            ], 500);
        }
    }
    
    /**
     * Get authenticated user profile.
     */
    public function show(Request $request): JsonResponse
    {
        return response()->json([
            'success' => true,
            'data' => new UserResource($request->user()),
        ]);
    }
}

Step 6: Register Service Provider

<?php
// app/Providers/RepositoryServiceProvider.php

namespace App\Providers;

use App\Repositories\Contracts\UserRepositoryInterface;
use App\Repositories\Eloquent\UserRepository;
use Illuminate\Support\ServiceProvider;

class RepositoryServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     */
    public function register(): void
    {
        // Bind repository interfaces to implementations
        $this->app->bind(
            UserRepositoryInterface::class,
            UserRepository::class
        );
    }

    /**
     * Bootstrap services.
     */
    public function boot(): void
    {
        //
    }
}

Register the provider:

// bootstrap/providers.php

return [
    App\Providers\AppServiceProvider::class,
    App\Providers\RepositoryServiceProvider::class,
];

Step 7: Define Routes

<?php
// routes/api.php

use App\Http\Controllers\Api\V1\UserController;
use Illuminate\Support\Facades\Route;

/**
 * API Version 1 Routes
 * 
 * Pattern: /api/v1/{resource}
 * All routes return JSON
 * Rate limiting: 60 requests/minute for authenticated, 20 for guests
 */
Route::prefix('v1')->group(function () {
    
    // Public routes
    Route::post('/users', [UserController::class, 'store'])
        ->name('api.v1.users.store');
    
    // Protected routes (require authentication)
    Route::middleware('auth:sanctum')->group(function () {
        Route::get('/users/me', [UserController::class, 'show'])
            ->name('api.v1.users.show');
    });
});

Step 8: Test the Endpoint

# Test user registration
$ curl -X POST http://localhost/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "SecurePass123",
    "password_confirmation": "SecurePass123"
  }'

# Expected response (201 Created)
{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "id": "9b3f4c8e-5d0a-4e7f-9c1b-2a3d4e5f6a7b",
    "name": "John Doe",
    "email": "john@example.com",
    "email_verified": false,
    "email_verified_at": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "token": "1|abc123..."
}

# Test authenticated endpoint
$ curl -X GET http://localhost/api/v1/users/me \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Accept: application/json"

# Test validation error
$ curl -X POST http://localhost/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Jane",
    "email": "invalid-email",
    "password": "123"
  }'

# Expected response (422 Unprocessable Entity)
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": ["The email must be a valid email address."],
    "password": ["Password must be at least 8 characters long.", "The password confirmation does not match."]
  }
}

Common Setup Mistakes & Solutions

Mistake #1: Not Using Database Transactions

The Problem:

// ❌ BAD: No transaction protection
public function createOrder($userId, $items)
{
    $order = Order::create(['user_id' => $userId]);
    
    foreach ($items as $item) {
        OrderItem::create([...]);  // If this fails, orphaned order!
    }
    
    $this->chargePayment($userId, $total);  // Payment charged but items failed!
}

The Solution:

// ✅ GOOD: Wrapped in transaction
public function createOrder($userId, $items)
{
    return DB::transaction(function () use ($userId, $items) {
        $order = Order::create(['user_id' => $userId]);
        
        foreach ($items as $item) {
            OrderItem::create([...]);
        }
        
        $this->chargePayment($userId, $total);
        
        return $order;
    });
}

Real-world impact: A client lost $12k when payments were charged but orders weren't created due to missing transaction protection.

Mistake #2: Exposing Internal IDs

The Problem:

// ❌ BAD: Sequential IDs leak information
GET /api/users/1
GET /api/users/2  // Attacker knows you have 2 users!

The Solution:

// ✅ GOOD: UUIDs prevent enumeration
GET /api/users/9b3f4c8e-5d0a-4e7f-9c1b-2a3d4e5f6a7b

Mistake #3: Not Logging Enough Context

The Problem:

// ❌ BAD: Useless log message
Log::error('User creation failed');

The Solution:

// ✅ GOOD: Actionable log message
Log::error('User creation failed', [
    'email' => $data['email'],
    'error' => $e->getMessage(),
    'trace' => $e->getTraceAsString(),
    'request_id' => $request->id(),
    'ip' => $request->ip(),
]);

Mistake #4: Missing Rate Limiting Configuration

The Problem: API gets hammered by bots, server crashes.

The Solution:

// config/sanctum.php
'middleware' => [
    'throttle:api',  // Uses APP_RATE_LIMIT from .env
],

// Advanced: Custom rate limits per endpoint
Route::middleware('throttle:10,1')->group(function () {
    Route::post('/login', [...]);  // 10 attempts per minute
});

Mistake #5: Not Testing Database Indexes

The Problem:

// Query looks innocent
User::where('email', $email)->first();  // 200ms with 100k users!

The Solution:

# Use Laravel Telescope or enable query logging
$ ./vendor/bin/sail artisan tinker
>>> DB::enableQueryLog();
>>> User::where('email', 'test@example.com')->first();
>>> DB::getQueryLog();

# Check if index is used
EXPLAIN SELECT * FROM users WHERE email = 'test@example.com';

Performance Baseline & Monitoring

Setting Up Laravel Telescope

# Access Telescope dashboard
http://localhost/telescope

# Monitor queries, requests, exceptions, logs in real-time

Key metrics to watch:

• Query count per request: Should be <10 for most endpoints
• Response time: Should be <100ms for simple endpoints
• Memory usage: Should be <10MB per request
• Cache hit rate: Should be >80% for hot data

Performance Testing Script

# Install Apache Bench (comes with Apache)
$ sudo apt-get install apache2-utils

# Test baseline performance
$ ab -n 1000 -c 10 -H "Accept: application/json" \
  http://localhost/api/v1/users/9b3f4c8e-5d0a-4e7f-9c1b-2a3d4e5f6a7b

# Expected output:
Requests per second:    500.00 [#/sec] (mean)
Time per request:       20.000 [ms] (mean)
Time per request:       2.000 [ms] (mean, across all concurrent requests)

Baseline targets:

• Simple GET: 500-1000 req/sec
• CREATE with validation: 200-400 req/sec
• Complex query with joins: 100-200 req/sec

Database Query Optimization

// Add this to a service provider to catch slow queries
DB::listen(function ($query) {
    if ($query->time > 100) {  // Log queries > 100ms
        Log::warning('Slow query detected', [
            'sql' => $query->sql,
            'time' => $query->time,
            'bindings' => $query->bindings,
        ]);
    }
});

Key Takeaways

1. Architecture matters more than framework choice - Repository-Service-Controller pattern prevents refactoring hell

2. Use Docker/Sail from day one - Environment parity prevents 90% of "works on my machine" issues

3. Log everything with context - Future you will thank present you when debugging production issues

4. UUIDs for public IDs - Prevents enumeration attacks and supports distributed systems

5. Database transactions are non-negotiable - One missing transaction can cost thousands in inconsistent data

6. Cache strategically - User lookups are prime candidates (80% query reduction)

7. Monitor from day one - Telescope catches issues before they reach production

8. Rate limiting is essential - Protect your API from abuse and accidental DDOS

What's Next

In Part 2: Advanced Features & Business Logic, we'll build:

• Authentication system with Sanctum (API tokens, password reset, email verification)
• Advanced filtering & sorting with query builders
• File uploads to S3 with progress tracking
• Background jobs & queues for heavy processing
• Real-time features with websockets
• API versioning strategies for backward compatibility
• Custom exception handling with detailed error responses

Preview snippet - Part 2:

// Advanced query builder for filtering products
GET /api/v1/products?filter[price_lte]=1000&sort=-created_at&include=user

// Response transformer with includes
{
  "data": [...],
  "meta": {
    "current_page": 1,
    "total": 150,
    "per_page": 15
  },
  "links": { ... }
}

Stay tuned for Part 2 where we tackle complex real-world scenarios!

Questions or feedback? Drop a comment below. I respond to every one.

Found this helpful? Share it with your team. Building production APIs is a team sport.