API Entwicklung in Laravel: Best Practices aus unseren API-First Projekten
API Entwicklung verbindet Systeme, automatisiert Geschäftsprozesse und ist die Grundlage moderner Web-, Mobile- und KI-Anwendungen. Wir zeigen, wie wir bei Laramate API-First Laravel Projekte aufsetzen, dokumentieren und absichern. Inklusive unserer praxiserprobten Empfehlungen zu Scramble, spatie/laravel-query-builder und der Nutzung von DTO-Paketen.
Die API Entwicklung verbindet Backend und Frontend, bedient mobile Apps, integriert Drittsysteme und stellt Daten für KI-Agenten bereit. Architektur und Dokumentation einer API entscheiden darüber, wie aufwendig spätere Erweiterungen werden.
Dieser Beitrag fasst zusammen, wie wir API-First Projekte mit Laravel aufsetzen. Sie finden konkrete Empfehlungen zu Architektur, Dokumentation, Filterlogik und Datenmapping. Die Hinweise kommen aus aktiven Projekten, unter anderem aus PIA Health und der KAT-TOOL App.
Eine produktionsreife Laravel API besteht für uns aus vier Bausteinen: einer API-First Architektur, einer automatisch generierten Dokumentation mit Scramble, einer einheitlichen Filterlogik mit spatie/laravel-query-builder und einer Datenmapping-Schicht, die zum jeweiligen Projekt passt.
Welchen Mehrwert bringt API Entwicklung Ihrem Unternehmen?
APIs zahlen sich dort aus, wo Geschäftsprozesse beschleunigt, Daten zentralisiert oder neue Vertriebskanäle eröffnet werden. Vier Anwendungsfelder sehen wir regelmäßig in Kundenprojekten:
CRM, ERP, Buchhaltung und Marketing-Tools liefern ein konsistentes Datenbild, wenn sie über APIs miteinander kommunizieren. Eine zentrale Laravel API als Hub reduziert manuelle Pflege und Datenfehler.
Bestellabwicklung, Rechnungsversand, Reporting und Datenabgleich laufen automatisiert ab. Manuelle Tätigkeiten entfallen, Übertragungsfehler werden reduziert.
Eine gut dokumentierte API ist die Voraussetzung dafür, dass KI-Agenten und LLMs auf Ihre Geschäftslogik zugreifen können. Ohne dokumentierte Schnittstellen bleiben KI-Use-Cases auf isolierte Prototypen beschränkt.
Eine API-First Anwendung bedient Web, Mobile und Partner mit derselben Codebasis. Neue Channels lassen sich anbinden, ohne das Backend umzubauen.
Wann lohnt sich der API-First-Ansatz?
API-First bedeutet, dass die API vor dem Frontend entworfen wird. Endpoints, Datenmodelle und Authentifizierung werden zuerst spezifiziert. Frontend, Mobile App und Drittsysteme bauen anschließend auf dieser stabilen Vertragsbasis auf.
Nicht jedes Projekt braucht diesen Ansatz. Eine schlanke Marketing-Site oder ein interner Prototyp kommt ohne aus. In folgenden Konstellationen setzen wir API-First standardmäßig ein:
Wenn eine native oder React Native App geplant ist, nutzen Web und Mobile dieselben Endpoints und dieselbe Authentifizierungslogik.
Wenn zwei Teams gleichzeitig arbeiten, verhindert ein klar spezifizierter API-Vertrag Reibungsverluste. Frontend kann gegen Mocks entwickeln, ohne auf das Backend zu warten.
Wenn Partnerintegrationen absehbar sind, wird die API von Anfang an als öffentliche Schnittstelle gebaut. Nachträgliches Absichern erfordert in der Regel zusätzliche Anpassungen an Authentifizierung, Rate Limiting und Dokumentation.
In Setups mit Microservices oder mehreren Backends sorgt API-First für klare Verantwortlichkeiten und stabile Verträge zwischen den Diensten.
Wie strukturieren wir API-Projekte in Laravel?
Eine Laravel API folgt bei uns einer wiederkehrenden Struktur. Drei Punkte sind dabei zentral.
Welche Authentifizierung wählen wir wann?
Authentifizierung ist die erste Architekturentscheidung. Wir wählen abhängig vom Anwendungsfall:
Laravel Sanctum für eigene Single-Page-Anwendungen und Mobile Apps. Sanctum ist leichtgewichtig, gut integriert und für die meisten Projekte vollkommen ausreichend.
Laravel Passport oder OAuth 2.0 wenn Drittanbieter Tokens für Endkunden ausstellen müssen. OAuth 2.0 mit OpenID Connect ist der Industriestandard für Multi-Client-Szenarien.
Personal Access Tokens für Server-zu-Server Integrationen. Hier reicht ein langlebiger Token mit klar abgegrenzten Scopes.
Scopes oder Abilities definieren wir frühzeitig, auch wenn die App initial nur eine Rolle hat. Eine spätere Nachrüstung erfordert Anpassungen an Tokens, Middleware und vergebenen Berechtigungen.
Wie versionieren wir unsere APIs?
Versionierung ist Pflicht, sobald eine API von einem zweiten Team oder einer Mobile App genutzt wird. Wir setzen in der Regel auf URL-basierte Versionierung mit dem Präfix /api/v1, /api/v2 und so weiter. Diese Variante ist explizit, lesbar und einfach in Routing, Logs und Monitoring zu erkennen.
Header-basierte Versionierung ist schwerer zu testen, schlechter dokumentierbar und in Caching-Layern eine häufige Fehlerquelle. Wir setzen sie nur ein, wenn die API ausschließlich von Maschinen mit fixem Client-Code konsumiert wird.
Wie halten wir Antworten konsistent?
Wir nutzen Laravel API-Resources oder Data-Klassen für jeden Endpoint, definieren ein einheitliches Response-Envelope mit data, meta und errors und arbeiten mit typisierten Statuscodes. Das hält Client- und Frontend-Code kürzer und reduziert Fallunterscheidungen.
Wie dokumentieren wir API-First Laravel Projekte?
Eine API ist nur so nützlich wie ihre Dokumentation. Wir haben mehrere Tools im Einsatz gehabt und nutzen heute durchgängig einen Standard.
Was leistet dedoc/scramble?
Wir dokumentieren unsere Laravel APIs mit Scramble von dedoc. Scramble erzeugt eine vollständige OpenAPI-Spezifikation direkt aus dem PHP-Code. Es liest Form Requests, Resources, Routen-Annotationen und Controller-Methoden und erstellt daraus eine OpenAPI-3.1-Datei sowie ein interaktives Frontend.
Der Vorteil: Es gibt keine separate Dokumentationsdatei, die mit dem Code aus dem Takt geraten kann. Jeder Endpoint, der im Code existiert, erscheint automatisch in der Dokumentation. Der Wartungsaufwand für die API-Dokumentation entfällt damit weitgehend.
Wann setzen wir Scramble Pro ein?
Die kostenlose Version von Scramble deckt den Großteil unserer Anforderungen ab. In Projekten mit mehreren Auth-Schemes, mehrsprachigen API-Texten, geschachtelten Resources oder Custom Response Shapes greifen wir aber zu Scramble Pro. Pro liefert genauere Type-Inferenz, bessere Polymorphie-Unterstützung und ein deutlich saubereres Schema bei komplexen Strukturen.
Sobald ein Projekt mehr als rund zwanzig Endpoints umfasst oder eine externe Schnittstelle bedient, setzen wir Scramble Pro ein. Die Lizenzkosten liegen unter dem Aufwand, den eine händisch gepflegte Dokumentation in der gleichen Größenordnung verursacht.
Ein einfaches Setup-Beispiel zeigt, wie wenig Konfiguration nötig ist:
<?php
// app/Http/Controllers/Api/V1/InspectionController.php
namespace App\Http\Controllers\Api\V1;
use App\Http\Requests\StoreInspectionRequest;
use App\Http\Resources\InspectionResource;
use App\Models\Inspection;
class InspectionController
{
/**
* List inspections.
*
* Returns a paginated list of farm inspections for the authenticated user.
*/
public function index(): \Illuminate\Http\Resources\Json\ResourceCollection
{
return InspectionResource::collection(
Inspection::query()
->forUser(auth()->user())
->latest()
->paginate()
);
}
/**
* Create a new inspection.
*/
public function store(StoreInspectionRequest $request): InspectionResource
{
$inspection = Inspection::create($request->validated());
return InspectionResource::make($inspection);
}
}Language:phpScramble liest Typehints, Docblocks und das Schema des Form Request, um den Endpoint vollständig zu beschreiben. Saubere Typisierung und konsequenter Einsatz von Form Requests reichen aus, damit die Dokumentation ohne weiteren Pflegeaufwand aktuell bleibt.
Welche Filter- und Sortierlogik setzen wir ein?
Sobald eine API Listen-Endpoints anbietet, kommen Filter, Sortierung und sparsame Feldauswahl ins Spiel. Wir setzen dafür konsequent spatie/laravel-query-builder ein. Das Paket etabliert ein einheitliches Query-Format auf URL-Ebene und schützt automatisch vor unerwünschten Filterkombinationen.
Ein typischer Index-Endpoint aus einem unserer aktiven Projekte sieht so aus:
<?php
use App\Data\LocationData;
use App\Models\Location;
use Illuminate\Contracts\Pagination\Paginator as PaginatorContract;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Spatie\QueryBuilder\QueryBuilder;
public function index(Request $request): PaginatorContract
{
$locations = QueryBuilder::for(Location::byUser(Auth::user()))
->allowedIncludes('address', 'departments', 'departments.members')
->paginate($request->input('per_page', 100));
return LocationData::collect($locations);
}Language:phpVier Dinge sind hier bewusst zusammengestellt:
Autorisierung am Modell. Der byUser-Scope kapselt die Sichtbarkeitslogik im Modell. Der Controller bleibt schlank und der Scope ist in Tests einfach einzeln prüfbar.
Includes statt N+1. allowedIncludes erlaubt dem Frontend, Beziehungen wie Adresse, Abteilungen und Mitglieder gezielt mitzuladen. Das ersetzt mehrere Roundtrips durch eine einzige, optimierbare Query.
Konfigurierbares per_page. Die Seitengröße liegt beim Client und hat einen sinnvollen Default. Listen-Endpoints lassen sich so für Tabellen, Auto-Complete oder Bulk-Sync passend abrufen.
Antwort über ein Data-Objekt. LocationData::collect liefert eine konsistent typisierte Antwort und ist die schlanke Variante für ein klares Datenmapping.
Bei Bedarf ergänzen wir den Builder um allowedFilters und allowedSorts, um Filter- und Sortierregeln explizit freizugeben. Drei strukturelle Vorteile haben sich dabei in unseren Projekten klar bewährt:
Klar definiertes Frontend-Vertragsmodell. Frontend und Mobile-Team wissen genau, welche Filter, Sortierungen und Includes erlaubt sind.
Klar definiertes Frontend-Vertragsmodell. Frontend und Mobile-Team wissen genau, welche Filter, Sortierungen und Includes erlaubt sind.
Sicherheit per Default. Nicht freigegebene Filter sind nicht ansprechbar. Das verhindert versehentliches Datenleck über kreative Query-Strings.
Saubere Integration mit Scramble. Die erlaubten Parameter erscheinen automatisch in der OpenAPI-Spezifikation und damit in der API-Dokumentation.
Wir setzen das Paket projektübergreifend ein, auch in Anwendungen mit dutzenden Endpoints.
Wie halten wir Logik aus dem Controller heraus?
Wir setzen das Action-Pattern für jede Operation ein, die unsere API ausführen soll. Das gilt für Schreibvorgänge, komplexere Lesevorgänge mit Berechnungen, Imports und Side Effects wie Mailversand oder Webhook-Trigger. Der Controller bleibt auf seine eigentliche Aufgabe beschränkt: Request annehmen, autorisieren, an die passende Action übergeben, Antwort zurückgeben. Geschäftslogik liegt in Action-Klassen aus.
Eine typische Update-Methode aus einem unserer Projekte sieht damit so aus:
<?php
use App\Actions\Reports\UpdateOrCreateReportAction;
use App\Data\ReportData;
use App\Models\Report;
use Illuminate\Support\Facades\Gate;
public function update(ReportData $reportData): ReportData
{
$report = Report::with('department.location')->findOrFail($reportData->id);
Gate::authorize('update', $report);
$report = (new UpdateOrCreateReportAction($reportData))->handle();
return ReportData::from($report);
}Language:phpVier Aspekte sind in diesem Muster zentral:
Eingang und Ausgang sind typisiert. Der Controller nimmt ein Data-Objekt entgegen und gibt eines zurück. Der API-Vertrag bleibt sauber, ohne dass das Eloquent-Modell durchschlägt.
Autorisierung sitzt nah am Controller. Gate::authorize lebt im Request-Kontext und greift auf den authentifizierten Nutzer zu. Die Action selbst muss sich darum nicht kümmern und bleibt damit auch in Queue-Jobs oder Tests einsetzbar.
Geschäftslogik liegt in einer testbaren Action. UpdateOrCreateReportAction lässt sich isoliert testen, in einer Console-Routine wiederverwenden und ohne Controller in einem Queue-Job ausführen.
Side Effects bleiben klar verortet. Mails, Notifications, Webhook-Trigger oder Audit-Logs gehören in die Action, nicht in den Controller. Wenn ein Endpoint später durch einen Cron-Job oder Webhook abgelöst wird, müssen Sie die Logik nicht anfassen.
Mehr zum Aufbau und Nutzen unserer Actions finden Sie im Beitrag Actions: Mehr Ordnung in der Laravel Business-Logik.
Wann lohnen sich DTO-Pakete und wann eigene Mapper?
Data Transfer Objects sind eine bewährte Idee. Sie kapseln eingehende und ausgehende Daten, bringen Typensicherheit und reduzieren das Hantieren mit lockeren Arrays. Im Laravel-Ökosystem gibt es dafür beliebte Pakete wie spatie/laravel-data oder eigene Implementierungen.
Unsere Empfehlung ist hier zweistufig.
Wann ein DTO-Paket Mehrwert liefert
Für einfache, weitgehend flache Datenstrukturen sind DTO-Pakete ein passender Einstieg. Sie reduzieren Boilerplate, validieren in einigen Implementierungen automatisch und lassen sich mit API-Resources kombinieren. Wenn das Datenmodell eng am Eloquent-Modell liegt und die Mapping-Regeln überschaubar sind, ist ein Paket die kürzere Variante.
Warum wir bei komplexem Mapping eigene Klassen schreiben
Bei komplexen Datenmappings kommen DTO-Pakete schnell an ihre Grenzen. Beispielsweise dann, wenn ein eingehendes Payload aus mehreren Quellen zusammengesetzt wird, mehrere interne Modelle berührt, abhängige Berechnungen anstößt oder spezifische Audit-Logs benötigt.
Wir haben in mehreren Projekten den Versuch unternommen, solche Strukturen mit einem Paket abzubilden. Wiederkehrend traten dieselben Effekte auf: längere Einarbeitung für neue Entwickler, Workarounds für Edge Cases und Lösungen, in denen ein größerer Anteil des Codes die Konventionen des Pakets umgeht.
Für komplexe Mappings setzen wir daher auf eigene, schlanke Mapper-Klassen. Sie sind direkt im Projekt-Code lesbar, einfach zu testen und folgen genau den Konventionen, die das Projekt ohnehin verwendet. Eine Klasse mit den Methoden fromRequest, toModel und toResource ist in der Regel in kurzer Zeit umgesetzt.
DTO-Pakete passen gut zu Standardanforderungen. Bei komplexen Datenmappings führt der Paketansatz häufig zu Workarounds. Eigene Mapper-Klassen halten die Logik im Projekt-Code lesbar und einfacher änderbar.
Welche Sicherheitsmaßnahmen sind in der Produktion Pflicht?
Folgende Punkte sind in unseren produktiven Laravel API-Projekten gesetzt:
Jeder Endpoint ist auth-geschützt. Scopes oder Abilities trennen Lesen, Schreiben und administrative Operationen sauber voneinander.
Laravel Rate Limiter pro Endpoint und pro Token-Identität. Login- und Schreib-Endpoints werden bewusst strenger limitiert als Read-Endpoints.
Form Requests prüfen jedes Feld. Unbekannte Felder werden bewusst zurückgewiesen, damit kein stilles Schema-Drift entsteht.
Alle Schreibvorgänge laufen in ein strukturiertes Log mit User-ID, Token-Identität und Request-ID. Audits und Fehlersuche werden damit auf konkrete Requests zurückführbar.
Sentry oder Bugsnag sind in jedem unserer API-Projekte aktiv. Fehler werden in Echtzeit gemeldet und mit Request-Kontext angereichert.
API-Keys, Token und Webhook-Signaturen liegen ausschließlich in der Umgebung, niemals im Repository. Wir setzen auf rotierbare Secrets und versenden Webhook-Payloads nur signiert.
Welche Fehler sehen wir am häufigsten in API-Projekten?
In Code-Audits an fremden Codebasen begegnen uns vier Fehlerbilder besonders häufig.
Eine API ohne Version funktioniert, bis der erste Breaking Change ansteht. Anschließend müssen Clients und Server gleichzeitig migriert werden. Wir setzen von Beginn an ein /v1, auch wenn keine zweite Version absehbar ist.
Ein Endpoint liefert ein Array, der nächste ein Objekt, der dritte direkt das Eloquent-Modell. Frontend-Code wird damit unnötig komplex und fehleranfällig.
Manuell gepflegte Markdown-Dokumentationen geraten nach wenigen Sprints aus dem Takt. Eine codenahe Generierung mit Scramble bleibt automatisch synchron zum Stand der Anwendung.
Wird ein DTO-Paket für einen Use Case eingesetzt, der mehrere Datenquellen zusammenführt, entstehen häufig Workarounds. Eigene Mapper-Klassen sind hier kürzer, im Projekt-Code direkt lesbar und ohne externe Konventionen testbar.
Wie unterstützen wir Sie bei Ihrem API-Projekt?
Wir begleiten Unternehmen von der ersten Architekturentscheidung bis zum produktiven Betrieb ihrer Laravel API. Typische Einstiegspunkte sind ein Laravel Code Audit für bestehende Anwendungen, ein Architektur-Workshop für neue Projekte oder die direkte Umsetzung als API-First Build.
Wenn Sie eine Laravel API planen oder eine bestehende API stabilisieren möchten, sprechen Sie uns gerne an. Im kostenlosen Erstgespräch klären wir Architektur- und Toolchain-Fragen für Ihr Projekt.
Eine API ist die Schnittstelle, über die Web, Mobile, Partner und KI-Agenten auf Ihre Anwendung zugreifen. Architektur, Dokumentation und Mapping legen fest, wie aufwendig spätere Erweiterungen, neue Channels und Integrationen werden.
