Roadrunner

Overview Building an API is a rite of passage for many developers, but building one that remains stable under load, remains easy to maintain, and provides a delightful developer experience is an entirely different challenge. This guide focuses on creating performant APIs by leaning heavily into the Laravel ecosystem. We explore how to move beyond basic CRUD operations to implement advanced route management, standardized response objects, robust caching strategies, and asynchronous write operations. The goal is to maximize the tools Laravel provides out of the box to build systems that scale gracefully without immediately reaching for third-party dependencies. Prerequisites To follow this tutorial, you should have a solid grasp of: - **PHP 8.2+**: Familiarity with modern features like read-only classes and enums. - **Laravel Fundamentals**: Understanding of Eloquent, Controllers, and Migrations. - **RESTful Concepts**: Basic knowledge of HTTP methods (GET, POST, etc.) and status codes. - **Composer**: Ability to manage PHP dependencies. Key Libraries & Tools - Laravel Framework: The primary PHP framework used for building the API. - Eloquent ORM: Laravel's built-in database mapper used for data retrieval and manipulation. - Laravel Query Builder: While the tutorial emphasizes native tools, Spatie's package is highlighted as a premier tool for filtering and sorting. - Laravel Vapor: Mentioned as a serverless deployment platform for extreme scaling. - Octane: A high-performance application server for Laravel that utilizes Swoole or RoadRunner. - Redis / Database: Used as the caching driver back-end. Section 1: Strategic Route Management and Versioning Organization is the first step toward performance. Visual overload and cognitive stress are real issues when your `api.php` file swells to hundreds of lines. Instead of a monolithic file, you should modularize your routes by resource and version them from day one. Versioning the API Versioning prevents breaking changes for your consumers. By prefixing your routes with `V1`, `V2`, etc., you can iterate on specific endpoints without disrupting existing integrations. ```php Route::prefix('v1')->name('v1:')->group(function () { Route::prefix('conversations')->name('conversations:')->group(base_path('routes/api/v1/conversations.php')); Route::prefix('messages')->name('messages:')->group(base_path('routes/api/v1/messages.php')); }); ``` Standalone API Configuration If you are building a standalone API, you might want to remove the default `api` prefix provided by Laravel. This is done in the application bootstrap or a service provider by setting the prefix to an empty string. This creates a cleaner URL structure like `https://api.myapp.test/v1/conversations`. Section 2: Standardizing Data with API Resources Performance isn't just about speed; it's about the size of the payload sent over the wire. Laravel API Resources act as a transformation layer between your Eloquent models and the JSON response. They allow you to be surgical about what data is exposed. The Conversation Resource By defining a resource, you ensure consistency across your application. Every time a conversation is returned, it follows the same shape. Use the `whenLoaded` method to prevent N+1 query issues when including relationships like a sender. ```php namespace App\Http\Resources\V1; use Illuminate\Http\Resources\Json\JsonResource; class ConversationResource extends JsonResource { public function toArray($request): array { return [ 'id' => $this->id, 'name' => $this->name, 'sender' => new UserResource($this->whenLoaded('sender')), '_links' => [ 'self' => route('v1:conversations:show', $this->id), ], ]; } } ``` Managing Pagination Payloads Standard Laravel pagination includes a lot of metadata that API consumers might not need, such as raw CSS class names for UI buttons. Using `simplePaginate()` reduces the payload size significantly by only providing the current page and indicators for more data, which is faster to calculate and transmit. Section 3: Advanced Response Objects and 'Responsible' Interfaces A common mistake is returning raw arrays from controllers. For a truly performant and discoverable API, implement the `Responsible` interface. This allows you to create dedicated response classes that handle their own logic, status codes, and headers. Creating a Collection Response Instead of the dreaded `data.data.data` nesting, a custom `CollectionResponse` class allows you to key your data meaningfully (e.g., `conversations` or `messages`) and include consistent metadata. ```php namespace App\Http\Responses\V1; use Illuminate\Contracts\Support\Responsable; use Illuminate\Http\JsonResponse; class CollectionResponse implements Responsable { public function __construct( private readonly mixed $data, private readonly string $key, private readonly int $status = 200 ) {} public function toResponse($request): JsonResponse { return new JsonResponse([ 'status' => $this->status, $this->key => $this->data, 'meta' => [ 'count' => count($this->data), ] ], $this->status); } } ``` Section 4: Proactive Caching and Cache Busting Caching is the most effective way to improve API read performance. However, "floating" cache keys (hardcoded strings scattered throughout the app) lead to stale data and debugging nightmares. Use PHP Enums to manage your cache keys and durations. The Forever Cache Pattern Rather than setting a Time-To-Live (TTL) of one hour and hoping for the best, cache your data forever and use Eloquent Observers to bust the cache immediately when data changes. This ensures the cache is always fresh and eliminates the "empty cache" performance hit that happens every hour. ```php namespace App\Observers; use App\Models\Conversation; use Illuminate\Support\Facades\Cache; use App\Enums\CacheKeys; class ConversationObserver { public function created(Conversation $conversation): void { Cache::forget(CacheKeys::conversations_for_user($conversation->sender_id)); } } ``` Warming the Cache You can further enhance performance by creating a scheduled command to "warm" the cache for your most active users. This ensures that even after a deployment or a cache flush, the first request a user makes is still served from the cache. Section 5: Asynchronous Write Operations with Jobs and Payloads Synchronous writes are a bottleneck. If a user creates a new conversation, the API should not wait for the database transaction and indexing to finish before responding. Instead, validate the request, dispatch a Laravel Job, and return a `202 Accepted` status code immediately. Implementing Data Payloads To pass data to background jobs safely, use Data Transfer Objects (DTOs) or simple Read-Only classes. This keeps your data immutable and structured. ```php namespace App\Jobs\V1; use App\Payloads\NewConversationPayload; use Illuminate\Bus\Queueable; use Illuminate\Contracts\Queue\ShouldQueue; use Illuminate\Support\Facades\DB; class CreateNewConversation implements ShouldQueue { use Queueable; public function __construct(private readonly NewConversationPayload $payload) {} public function handle(): void { DB::transaction(fn() => Conversation::create($this->payload->toArray()), 3); } } ``` By returning an immediate response, your API feels instantaneous to the user, even if the database work takes a few extra milliseconds in the background. Syntax Notes - **Read-only Classes**: Use `readonly class` to ensure data integrity for DTOs and Response objects. It prevents accidental state mutation during a request lifecycle. - **Attributes**: Features like `[ObservedBy(ConversationObserver::class)]` and `[AsCommand('warm:conversations')]` clean up service providers by keeping registration logic directly on the classes they affect. - **Named Routes**: Always name your API routes with a versioned prefix (e.g., `v1:conversations:index`). This makes generating links within API Resources much more resilient to URL changes. Practical Examples - **Real-time Chat**: Using the asynchronous write pattern allows a chat app to send a message and update the local UI instantly while the server processes the message in the background. - **Analytics Ingress**: At companies like Treblle, handling billions of requests monthly requires pushing every bit of processing to background workers and using Octane to keep the application in memory, reducing boot times. - **Public Data Feeds**: For APIs providing stock prices or weather data, the "Forever Cache + Observer" pattern ensures zero-latency reads with instant updates as soon as the source data changes. Tips & Gotchas - **The 'Data' Wrapper**: If your frontend team complains about `response.data.data`, check your `AppServiceProvider`. You can call `JsonResource::withoutWrapping()` to flatten your responses. - **Database Transactions**: When writing in background jobs, always include a retry count (e.g., `DB::transaction(..., 3)`). This prevents failures due to temporary deadlocks on highly active databases. - **Standardization vs. Consistency**: Don't lose sleep over following JSON:API or HAL standards perfectly. It is far better to be internally consistent across your own endpoints than to follow a standard poorly. - **Testing**: Never ship a performance optimization without a test. Use Laravel's fluent testing helpers to verify that your cache is actually being hit and that your background jobs are dispatched with the correct data.