Scalable API Architecture: Building Production-Ready Laravel Systems

Building Modern Laravel APIs: Foundations and Project Structure

Steve McDougall introduces Pulse-Link, a high-performance lead ingestion engine built on PHP 8.5 and Laravel 13. The system implements a strict layered architecture designed to prevent the common pitfalls of scaled production codebases.

Why This Matters

Standard framework scaffolding often lacks the necessary constraints for large-scale production APIs, resulting in codebases that resist modification as complexity grows. By enforcing architectural opinions like single-responsibility actions and strict model behavior early, engineers can maintain system integrity and avoid the technical debt associated with leaky abstractions.

Key Insights

• ULIDs provide non-sequential, time-sortable identifiers that prevent leaking data volume metrics to external consumers (Laravel 13 native).
• Invokable Controllers enforce a single-action responsibility, ensuring each HTTP endpoint has only one reason to change.
• Form Requests as DTOs decouple business logic from raw HTTP input by providing validated, typed objects via a payload() method.
• RFC 9457 compliant Problem+JSON responses standardize error handling, allowing clients to rely on a consistent structure for all failure states.
• HTTP Sunset and Deprecation headers facilitate API lifecycle management by signaling version retirement dates to consumers from day one.

Working Examples

The Lead model utilizing PHP 8.x attributes for fillable fields and native ULID support.

<?php
declare(strict_types=1);
namespace App\Models;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Model;

#[Fillable(
    'email', 'first_name', 'last_name', 'company', 'job_title', 'phone', 'source', 'raw_payload', 'enriched_data', 'score', 'status'
)]
final class Lead extends Model
{
    use HasUlids;
    protected function casts(): array
    {
        return [
            'raw_payload' => 'array',
            'enriched_data' => 'array',
            'score' => 'integer',
        ];
    }
}

Exception handler configuration for RFC 9457 Problem+JSON error responses.

$exceptions->render(function (ValidationException $e, Request $request): JsonResponse {
    return new JsonResponse(
        data: [
            'type' => 'https://httpstatuses.com/422',
            'title' => 'Unprocessable Entity',
            'status' => 422,
            'detail' => 'The given data was invalid.',
            'errors' => $e->errors(),
        ],
        status: 422,
        headers: ['Content-Type' => 'application/problem+json'],
    );
});

Practical Applications

• System: Pulse-Link lead ingestion. Behavior: Uses ULIDs to hide ingestion volume from competitors. Pitfall: Using auto-increment integers which allow external parties to estimate business growth.
• System: API Lifecycle Management. Behavior: Implementing ‘sunset’ middleware to notify clients of V1 deprecation. Pitfall: Introducing breaking API changes without a versioned migration path.
• System: Domain Logic Isolation. Behavior: Encapsulating enrichment logic in discrete Action classes for testability. Pitfall: Bloating controllers with business logic, making unit testing impossible.

References:

• https://dev.to/juststevemcd/building-modern-laravel-apis-foundations-and-project-structure-3ich