Laravel-API-Guide

Worum geht's?

Du kennst die API-Architekturen und willst sie in Laravel sauber umsetzen. Dieser Guide zeigt pro Architektur die Laravel-typischen Bausteine, die empfohlenen Pakete und die wichtigsten Best Practices.

Voraussetzung

Laravel 11+. Die Beispiele nutzen PHP 8.3-Syntax (Constructor Property Promotion, readonly, enums).

---

1. REST – das Brot-und-Butter-Pattern

Bausteine

• Routes: routes/api.php mit Route::apiResource
• Controller: Single-Action Controllers (Invokable) oder Resource-Controller
• FormRequest: Validation
• API-Resource: Output-Transformation
• Policy: Authorization

Routen

// routes/api.php
use App\Http\Controllers\Api\OrderController;

Route::middleware(['auth:sanctum', 'throttle:60,1'])->group(function () {
    Route::apiResource('orders', OrderController::class);
    Route::post('orders/{order}/cancel', [OrderController::class, 'cancel']);
});

Controller

// app/Http/Controllers/Api/OrderController.php
final class OrderController extends Controller
{
    public function index(IndexOrderRequest $request): AnonymousResourceCollection
    {
        $this->authorize('viewAny', Order::class);

        $orders = Order::query()
            ->forUser($request->user())
            ->filter($request->validated())
            ->latest()
            ->paginate(perPage: 25);

        return OrderResource::collection($orders);
    }

    public function store(StoreOrderRequest $request): JsonResponse
    {
        $order = app(CreateOrderAction::class)->execute(
            user: $request->user(),
            data: $request->validated(),
        );

        return OrderResource::make($order)
            ->response()
            ->setStatusCode(201);
    }
}

FormRequest + Resource

final class StoreOrderRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'items' => ['required', 'array', 'min:1'],
            'items.*.product_id' => ['required', 'integer', 'exists:products,id'],
            'items.*.quantity'   => ['required', 'integer', 'min:1', 'max:100'],
            'notes' => ['nullable', 'string', 'max:500'],
        ];
    }
}

final class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'       => $this->id,
            'status'   => $this->status->value,
            'total'    => $this->total->format(),
            'items'    => OrderItemResource::collection($this->whenLoaded('items')),
            'created'  => $this->created_at->toIso8601String(),
            'links'    => [
                'self'   => route('orders.show', $this->resource),
                'cancel' => route('orders.cancel', $this->resource),
            ],
        ];
    }
}

Best Practices

• Action-Klassen statt Fat-Controller-Methoden (CreateOrderAction, CancelOrderAction)
• Konsistente Fehlerformate via App\Exceptions\Handler (RFC 7807 / JSON:API)
• OpenAPI mit darkaonline/l5-swagger oder Scribe automatisch generieren
• API-Versionierung über URL-Prefix (/api/v1/) oder Accept-Header
• Pagination nur via paginate() (Cursor für unendliche Listen: cursorPaginate())
• Rate Limiting mit benannten Limitern in RouteServiceProvider
• Idempotency-Key-Header für POSTs prüfen (gegen Doppel-Submits)

Pakete

• Laravel Sanctum – Token-Auth für SPAs/Mobile
• Laravel Passport – OAuth2 Server
• Scribe – API-Doku-Generator
• Spatie Query Builder – Filter/Sort/Include aus Query-Params

---

2. GraphQL

Empfohlener Stack: Lighthouse

composer require nuwave/lighthouse
php artisan lighthouse:install

Schema-First

# graphql/schema.graphql
type Query {
    user(id: ID! @eq): User @find
    orders(
        status: OrderStatus @eq
        first: Int! = 25
        page: Int
    ): [Order!]! @paginate(defaultCount: 25)
}

type Mutation {
    createOrder(input: CreateOrderInput! @spread): Order!
        @field(resolver: "App\\GraphQL\\Mutations\\CreateOrder")
        @guard
}

type Order {
    id: ID!
    status: OrderStatus!
    total: String!
    items: [OrderItem!]! @hasMany
    user: User! @belongsTo
}

enum OrderStatus {
    PENDING
    PAID
    SHIPPED
    CANCELLED
}

input CreateOrderInput {
    items: [OrderItemInput!]!
    notes: String
}

Resolver

final class CreateOrder
{
    public function __construct(
        private readonly CreateOrderAction $action,
    ) {}

    public function __invoke(mixed $_, array $args, GraphQLContext $ctx): Order
    {
        return $this->action->execute(
            user: $ctx->user(),
            data: $args,
        );
    }
}

Best Practices

• N+1 vermeiden mit @hasMany, @belongsTo (Lighthouse löst das via DataLoader) oder eigenem BatchLoader
• Query-Komplexität limitieren: lighthouse.security.max_query_depth und max_query_complexity
• Persisted Queries im Frontend (Apollo) → schützt vor DoS und reduziert Payload
• Authorization: @guard, @can, eigene FieldMiddleware
• Subscriptions via Laravel Reverb / Pusher / Redis
• GraphiQL im Dev-Modus aktivieren, in Production deaktivieren
• Strict Schema: Niemals Any-Scalar – immer typisieren

Alternative

• Lighthouse – Schema-First, Defacto-Standard
• GraphQLite – Code-First mit Annotations
• rebing/graphql-laravel – Code-First klassisch

---

3. gRPC – Service-zu-Service

Empfohlener Stack: Spiral RoadRunner + spiral/php-grpc

PHP-FPM kann gRPC nicht effizient bedienen (kein HTTP/2-Multiplexing). RoadRunner (Go-basierter App-Server) löst das.

composer require spiral/roadrunner-grpc spiral/php-grpc

Proto

// proto/order.proto
syntax = "proto3";
package billing;

service OrderService {
    rpc GetOrder (OrderRequest) returns (Order);
    rpc StreamOrders (OrderFilter) returns (stream Order);
}

message OrderRequest { int32 id = 1; }
message Order {
    int32 id = 1;
    string status = 2;
    double total = 3;
}

Generierung & Service-Implementierung

protoc --php_out=app/Grpc --grpc-php_out=app/Grpc proto/order.proto

final class OrderServiceImpl implements OrderServiceInterface
{
    public function __construct(
        private readonly OrderRepository $orders,
    ) {}

    public function GetOrder(GRPC\ContextInterface $ctx, OrderRequest $in): Order
    {
        $order = $this->orders->find($in->getId())
            ?? throw new GRPCException('Order not found', StatusCode::NOT_FOUND);

        return (new Order())
            ->setId($order->id)
            ->setStatus($order->status->value)
            ->setTotal($order->total->amount());
    }
}

Best Practices

• mTLS für interne Service-Calls – RoadRunner unterstützt es nativ
• Proto-Files in eigenes Repo (oder packages/proto) – versioniert
• Backward Compatibility: Felder nie umnummerieren, nur hinzufügen
• Deadlines & Cancellation clientseitig immer setzen
• gRPC für intern – nach außen weiterhin REST/GraphQL als Edge

---

4. WebSocket – Echtzeit mit Laravel Reverb

Reverb ist Laravels offizieller, eigener WebSocket-Server (ab Laravel 11). Pusher-API-kompatibel, lokal lauffähig.

composer require laravel/reverb
php artisan reverb:install
php artisan reverb:start

Broadcasting-Event

final class OrderShipped implements ShouldBroadcast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(public readonly Order $order) {}

    public function broadcastOn(): array
    {
        return [new PrivateChannel("orders.{$this->order->id}")];
    }

    public function broadcastWith(): array
    {
        return [
            'tracking_url' => $this->order->tracking_url,
            'shipped_at'   => $this->order->shipped_at->toIso8601String(),
        ];
    }
}

Channel-Auth

// routes/channels.php
Broadcast::channel('orders.{order}', function (User $user, Order $order) {
    return $user->id === $order->user_id;
});

Client (Laravel Echo)

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: import.meta.env.VITE_REVERB_APP_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: 8080,
    forceTLS: false,
});

Echo.private(`orders.${orderId}`)
    .listen('OrderShipped', (e) => updateUI(e));

Best Practices

• PrivateChannel / PresenceChannel mit Auth, nie öffentlich für Userdaten
• Reverb hinter Reverse Proxy (Nginx mit proxy_set_header Upgrade)
• Skalierung horizontal via Redis-Pub/Sub-Backend
• Reconnect-Strategien im Echo-Client konfigurieren
• Whisper (.whisper()) für Client-zu-Client-Events (Typing-Indicators, Cursors)
• Heartbeat über pings_interval konfigurieren

Alternativen

• Soketi – externer Pusher-kompatibler Server (Node)
• Pusher Channels (SaaS)
• Ably (SaaS)

---

5. Server-Sent Events – LLM-Streaming, Notifications

Laravel kann SSE über StreamedResponse direkt liefern – kein Reverb nötig.

final class LlmStreamController
{
    public function __invoke(StreamRequest $request, ClaudeClient $claude): StreamedResponse
    {
        return response()->stream(function () use ($request, $claude) {
            foreach ($claude->stream($request->validated()) as $chunk) {
                echo "data: " . json_encode($chunk) . "\n\n";
                ob_flush();
                flush();
            }
            echo "event: done\ndata: {}\n\n";
        }, headers: [
            'Content-Type'      => 'text/event-stream',
            'Cache-Control'     => 'no-cache',
            'X-Accel-Buffering' => 'no',   // Nginx-Buffering aus
            'Connection'        => 'keep-alive',
        ]);
    }
}

Best Practices

• PHP-FPM Timeout und max_execution_time hochsetzen (oder via Octane)
• Nginx: proxy_buffering off für SSE-Routen
• Frontend EventSource mit automatischem Reconnect nutzen
• Authentifizierung über Query-Param oder Cookie – EventSource unterstützt keine Custom-Header
• Heartbeat-Events alle 15s, damit Proxies die Verbindung nicht killen
• Octane oder FrankenPHP in Production – klassisches PHP-FPM blockiert sonst Worker

---

6. Webhooks – eingehend

Ein eingehender Webhook (z. B. Stripe)

// routes/api.php
Route::post('webhooks/stripe', StripeWebhookController::class)
    ->withoutMiddleware([VerifyCsrfToken::class]);

final class StripeWebhookController
{
    public function __invoke(Request $request): Response
    {
        try {
            $event = Webhook::constructEvent(
                $request->getContent(),
                $request->header('Stripe-Signature'),
                config('services.stripe.webhook_secret'),
            );
        } catch (SignatureVerificationException) {
            abort(401, 'Invalid signature');
        }

        // Idempotenz: jeden Stripe-Event-Hash 1× behandeln
        if (WebhookLog::where('external_id', $event->id)->exists()) {
            return response('Already processed', 200);
        }

        ProcessStripeEvent::dispatch($event->toArray());

        WebhookLog::create(['external_id' => $event->id, 'type' => $event->type]);

        return response('OK', 200);
    }
}

Best Practices

• Signatur verifizieren – bei JEDEM Webhook
• Idempotenz über Event-ID-Tracking
• Sofort 2xx zurückgeben, schwere Arbeit in Queue-Job verschieben
• Logging in eigener Tabelle (webhook_logs) für Replay/Audit
• Spatie Webhook Client als fertiges Paket (spatie/laravel-webhook-client)

Ausgehende Webhooks (du verschickst)

→ spatie/laravel-webhook-server – HMAC-Signing, Retries, Backoff, Worker.

---

7. SOAP

PHP hat eingebauten SOAP-Support (ext-soap). In Laravel meist als Wrapper im Service.

final class ElsterClient
{
    private SoapClient $client;

    public function __construct(string $wsdl)
    {
        $this->client = new SoapClient($wsdl, [
            'trace'        => true,
            'exceptions'   => true,
            'soap_version' => SOAP_1_2,
            'cache_wsdl'   => WSDL_CACHE_BOTH,
        ]);
    }

    public function submitReport(array $data): SubmitResult
    {
        try {
            $response = $this->client->__soapCall('Submit', [$data]);
            return SubmitResult::fromResponse($response);
        } catch (SoapFault $e) {
            Log::error('SOAP fault', [
                'fault'       => $e->getMessage(),
                'request'     => $this->client->__getLastRequest(),
                'response'    => $this->client->__getLastResponse(),
            ]);
            throw new ElsterUnavailable($e->getMessage(), previous: $e);
        }
    }
}

Best Practices

• WSDL lokal cachen (cache_wsdl => WSDL_CACHE_BOTH)
• __getLastRequest/Response für Debugging einschalten
• Domain-Exceptions statt rohe SoapFaults nach oben werfen
• WSSecurity / Signing nur via offizielles Paket (robrichards/wse-php)
• Tests gegen WSDL-Mock (phpro/soap-client kann das)

---

8. tRPC-Bridge – Laravel als Backend für TS-Frontend

tRPC ist TS-only. Wenn du tRPC-Style-Type-Safety mit Laravel-Backend willst:

• Spatie Laravel Data + Spatie Typescript-Transformer generiert TS-Typen aus Laravel-Klassen.
• Inertia.js umgeht klassische APIs komplett – Laravel rendert Props, Vue/React empfängt sie typsicher.

// app/Data/OrderData.php
final class OrderData extends Data
{
    public function __construct(
        public readonly int $id,
        public readonly OrderStatus $status,
        public readonly string $total,
        /** @var DataCollection<int, OrderItemData> */
        public readonly DataCollection $items,
    ) {}
}

→ php artisan typescript:transform produziert eine resources/types/generated.d.ts mit OrderData als TS-Interface. Frontend nutzt es direkt.

---

9. Queues – asynchrone Workloads

Laravel's Queue-Layer ist eines seiner stärksten Features.

Job

final class ProcessStripeEvent implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 5;
    public int $backoff = 30;
    public int $timeout = 120;

    public function __construct(public readonly array $event) {}

    public function handle(StripeEventHandler $handler): void
    {
        $handler->process($this->event);
    }

    public function uniqueId(): string
    {
        return $this->event['id'];  // Idempotenz!
    }
}

Best Practices

• Treiber-Wahl: Redis (default), SQS für Cloud, RabbitMQ für komplexe Routings
• Horizon für Redis-Queues – Dashboard, Auto-Scaling, Metriken
• Backoff exponentiell bei Retry: [10, 30, 60, 120, 300]
• ShouldBeUnique für Idempotenz auf Lock-Ebene
• Batches für Job-Gruppen mit Callback-Logik
• Job-Middleware für Throttling externer APIs (new RateLimited('stripe-api'))
• Failed-Jobs-Table überwachen / Alerts setzen
• Tests: Queue::fake() und Bus::fake()

---

10. Event-Streaming mit Kafka / Redpanda

Für Event-Sourcing oder Hochlast-Pipelines.

composer require mateusjunges/laravel-kafka

// Producer
Kafka::publishOn('orders.events')
    ->withHeaders(['event-type' => 'OrderCreated'])
    ->withBodyKey('order_id', $order->id)
    ->withBodyKey('total', $order->total->amount())
    ->send();

// Consumer (in Artisan-Command)
Kafka::consumer(['orders.events'])
    ->withHandler(function (ConsumedMessage $message) {
        // …
    })
    ->build()
    ->consume();

Best Practices

• Schemas mit Avro oder Protobuf, registriert im Schema-Registry
• Consumer-Groups für horizontale Skalierung
• Idempotenz im Consumer (z. B. Outbox-Pattern für Producer)
• Dead-Letter-Topic für unbehandelbare Nachrichten

---

11. Gesamtarchitektur in Laravel – ein Beispiel

┌─────────────────────────────────────────────────────────────────────────┐
│ Edge / Public                                                           │
│   REST API (Sanctum + Scribe-Doku)         routes/api.php               │
│   GraphQL für SPA                          /graphql via Lighthouse      │
│   Webhooks von Stripe/GitHub               routes/api.php (signed)      │
├─────────────────────────────────────────────────────────────────────────┤
│ Realtime                                                                │
│   WebSocket (Reverb) für Live-UI           Broadcasting Events          │
│   SSE für LLM-Streaming                    StreamedResponse + Octane    │
├─────────────────────────────────────────────────────────────────────────┤
│ Service-zu-Service                                                      │
│   gRPC (RoadRunner) zu Pricing-Service     proto/*.proto                │
├─────────────────────────────────────────────────────────────────────────┤
│ Async / Background                                                      │
│   Redis-Queue + Horizon (Jobs)             app/Jobs                     │
│   Kafka (Event-Stream)                     Outbox-Pattern               │
├─────────────────────────────────────────────────────────────────────────┤
│ Legacy                                                                  │
│   SOAP-Client zu ELSTER                    app/Services/Elster*         │
└─────────────────────────────────────────────────────────────────────────┘

---

12. Cross-Cutting Best Practices in Laravel

Authentication

• SPA-Same-Domain: Sanctum Cookie-Mode
• Mobile / 3rd Party: Sanctum Personal Access Tokens oder Passport OAuth2
• Service-zu-Service: mTLS (gRPC) oder kurzlebige JWTs

Validation

• FormRequest-Klassen für REST/GraphQL-Inputs
• Spatie Data für typisierte DTOs
• Niemals Request-Daten direkt ins Eloquent-Model ohne Validation
• Enum-Casts für Status-Felder

Authorization

• Policies für Eloquent-Modelle
• Gates für globale Permissions
• AuthorizeResource in Controllern, @guard/@can in GraphQL

Fehlerformat (RFC 7807)

// app/Exceptions/Handler.php
$this->renderable(function (Throwable $e, Request $request) {
    if (! $request->expectsJson()) return null;

    return match (true) {
        $e instanceof ValidationException => response()->json([
            'type'   => 'https://example.com/errors/validation',
            'title'  => 'Validation failed',
            'status' => 422,
            'errors' => $e->errors(),
        ], 422),
        $e instanceof ModelNotFoundException => response()->json([
            'type'   => 'https://example.com/errors/not-found',
            'title'  => 'Resource not found',
            'status' => 404,
        ], 404),
        default => null,
    };
});

Logging & Observability

• Structured Logging (JSON-Format in Production)
• Telescope in Dev / Staging
• Sentry oder Bugsnag für Errors
• OpenTelemetry über open-telemetry/opentelemetry-laravel
• Per-Request-Trace-ID als Middleware (X-Request-Id)

Testing

// Pest
it('creates an order', function () {
    $user = User::factory()->create();

    $response = $this->actingAs($user)->postJson('/api/orders', [
        'items' => [['product_id' => 1, 'quantity' => 2]],
    ]);

    $response->assertCreated()
        ->assertJsonPath('data.status', 'pending');

    expect(Order::count())->toBe(1);
});

• Feature-Tests mit actingAs() für REST/GraphQL
• Event::fake(), Queue::fake(), Bus::fake() für Async
• Http::fake() für externe APIs / Webhooks
• gRPC: separate Tests gegen RoadRunner-Container in CI

Caching

• HTTP-Caching via etag()-Header und Cache-Control
• Eloquent-Cache sparsam – lieber gezielte Cache::remember in Actions
• Tagged Cache mit Redis für invalidierbare Gruppen

Rate Limiting

// app/Providers/RouteServiceProvider.php
RateLimiter::for('api', fn (Request $r) =>
    Limit::perMinute(60)->by($r->user()?->id ?: $r->ip())
);

RateLimiter::for('webhooks', fn (Request $r) =>
    Limit::perMinute(300)->by($r->ip())
);

API-Versionierung

• URL-Versionierung (/api/v1/...) – am pragmatischsten
• Header-Versionierung (Accept: application/vnd.example.v2+json) – eleganter, schwerer cachebar
• Niemals breaking changes ohne neue Version
• Deprecation-Header (Sunset, Deprecation) im Übergang

---

13. Pakete-Cheatsheet

Zweck	Paket
REST-Doku	knuckleswtf/scribe, darkaonline/l5-swagger
Query-Builder mit Filtern	spatie/laravel-query-builder
GraphQL	nuwave/lighthouse
gRPC	spiral/php-grpc, roadrunner-server/grpc
WebSocket	laravel/reverb, soketi/soketi
Webhooks (in)	spatie/laravel-webhook-client
Webhooks (out)	spatie/laravel-webhook-server
Data Transfer Objects	spatie/laravel-data
TS-Codegen	spatie/typescript-transformer
Inertia	inertiajs/inertia-laravel
Queue-Dashboard	laravel/horizon
Kafka	mateusjunges/laravel-kafka
Octane (Performance)	laravel/octane
FrankenPHP	dunglas/frankenphp
OpenAPI-Validation	hkulekci/kafka-laravel

---

14. Sicherheits-Checkliste (Laravel-spezifisch)

Vor Production prüfen

• APP_DEBUG=false in Production – immer
• HTTPS erzwingen via URL::forceScheme('https') oder Trusted-Proxy-Konfig
• CORS in config/cors.php explizit – keine * für Auth-Endpoints
• Sanctum stateful domains korrekt konfiguriert
• CSRF für Web-Routes aktiv, für API-Routes ausgenommen
• Mass Assignment: $guarded = [] nur mit FormRequest-Validation davor – sonst $fillable whitelisten
• Eloquent Scope forUser() überall, wo Multi-Tenancy gilt
• SQL-Injection via Query-Builder geschützt – nie roh DB::raw() mit User-Input
• Webhook-Signaturen prüfen (Stripe, GitHub, Mollie)
• Rate-Limiter auf JEDEM öffentlichen Endpoint
• Reverb: PrivateChannel mit Auth, niemals Channel für Userdaten
• gRPC: mTLS zwischen Services

---

15. Weiterführend

• API-Architekturen-Überblick → API-Architekturen
• Live-OpenAPI-Playground → API Playground
• Laravel-Coding-Guidelines deines Teams → BSH-Skill bsh-code-guideline

Externe Quellen

• Laravel Docs – API Resources
• Lighthouse GraphQL
• Laravel Reverb
• Spiral RoadRunner gRPC
• Spatie Packages

Quote

„Jede API-Architektur hat in Laravel ein gutes Paket – die Kunst liegt nicht in der Implementierung, sondern in der Wahl der richtigen Architektur für den richtigen Use-Case."