Wie entwirft man eine gute REST API? Praxisleitfaden

Eine gute REST API überrascht nicht. Entwickler können einen Endpunkt vorhersagen, Antworten ohne Servercode verstehen und Fehler ohne Rätselraten beheben. Diese Qualität entsteht durch konsistente Entscheidungen und einen klaren Vertrag.

Was macht eine REST API gut?

Eine starke API modelliert Geschäftsressourcen, folgt der HTTP-Semantik, liefert konsistentes JSON und hilfreiche Fehler, schützt Daten und entwickelt sich weiter, ohne vorhandene Clients zu brechen.

1. Ressourcen mit Substantiven modellieren

Verwenden Sie stabile Konzepte wie orders, customers und invoices. Bevorzugen Sie Pluralformen und /orders/42/items gegenüber /getOrderItems. Halten Sie Verschachtelung flach, damit Autorisierung und Wartung übersichtlich bleiben.

GET    /api/v1/orders
POST   /api/v1/orders
GET    /api/v1/orders/42
PATCH  /api/v1/orders/42
DELETE /api/v1/orders/42

2. HTTP-Methoden semantisch korrekt verwenden

GET liest ohne Zustandsänderung, POST erstellt oder startet eine nicht-idempotente Aktion, PUT ersetzt, PATCH aktualisiert teilweise und DELETE löscht. Die Semantik aus RFC 9110 lässt Clients, Caches und Werkzeuge korrekt arbeiten.

3. Präzise Statuscodes zurückgeben

Nutzen Sie 200 für Erfolg, 201 mit Location für Erstellung und 204 ohne Body. Unterscheiden Sie 400, 401, 403, 404, 409, 422 und 429. 5xx ist für Serverfehler reserviert.

4. JSON-Repräsentationen konsistent halten

Legen Sie Regeln für Feldnamen, Zeitangaben, Geld, Nullwerte und Umschläge fest. Verwenden Sie ISO 8601 mit Zeitzone. Geben Sie Datenbankspalten nicht versehentlich preis; die Antwort ist ein öffentlicher Vertrag.

{
  "data": {
    "id": 42,
    "status": "paid",
    "total": 129.90,
    "currency": "USD"
  }
}

5. Nützliche Fehler gestalten

Ein Fehler braucht stabilen Typ oder Code, Titel, HTTP-Status, sichere Erklärung, Feldfehler und Request-ID. RFC 9457 Problem Details definiert ein Standardformat.

{
  "type": "https://api.example.com/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "errors": {"email": ["The email field is required."]}
}

6. Collections standardisieren

Nutzen Sie klare Parameter wie ?status=paid&sort=-created_at&page=2&per_page=25. Dokumentieren Sie erlaubte Filter und Sortierungen und begrenzen Sie die Seitengröße. Cursor-Pagination eignet sich besser für große, schnell veränderliche Datenmengen.

7. Kompatibilität und Versionierung planen

Neue optionale Felder sind meist sicher; Umbenennen, Typänderungen und Entfernen sind Breaking Changes. Definieren Sie eine Strategie wie /api/v1, einen Deprecation-Zeitraum und Migrationshinweise.

8. Sicherheit in den Vertrag integrieren

Erzwingen Sie HTTPS, authentifizieren Sie Clients und autorisieren Sie jede Ressourcenaktion. Validieren Sie mit Allow-Lists, begrenzen Sie Größe und Rate und liefern Sie nie Secrets oder Stack Traces. Protokollieren Sie Sicherheitsereignisse ohne Zugangsdaten oder personenbezogene Daten.

9. Caching und Nebenläufigkeit

Verwenden Sie bei sicheren Lesezugriffen Cache-Control, ETag und bedingte Requests. Akzeptieren Sie If-Match oder eine Versionsnummer gegen verlorene Updates. Idempotency Keys schützen wiederholte Zahlungs- und Erstellungsanfragen.

10. Dokumentieren und testen

Pflegen Sie einen OpenAPI-Vertrag mit Beispielen für Erfolg, Validierung, Authentifizierung und Rate Limits. Nutzen Sie ihn für Dokumentation, SDKs, Schema- und Contract-Tests. Ergänzen Sie Korrelations-IDs, strukturierte Logs, Metriken und Tracing.

Eine saubere REST API mit Laravel

Route::apiResource erstellt konventionelle CRUD-Routen, Sanctum authentifiziert Clients und Throttle-Middleware schützt Endpunkte.

use App\Http\Controllers\Api\OrderController;
use Illuminate\Support\Facades\Route;

Route::prefix('v1')
    ->middleware(['auth:sanctum', 'throttle:api'])
    ->group(function () {
        Route::apiResource('orders', OrderController::class);
    });

Nutzen Sie Form Requests für Validierung und Autorisierung, Policies für Ressourcenrechte und API Resources für den JSON-Vertrag. Controller koordinieren HTTP; komplexe Geschäftslogik gehört in Services oder Actions.

public function show(Order $order): OrderResource
{
    return new OrderResource($order);
}

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'status' => $this->status,
        'total' => $this->total,
        'currency' => $this->currency,
    ];
}

REST-API-Checkliste

• Klare, plurale, vorhersehbare Ressourcen-URLs
• Korrekte HTTP-Methoden und Statuscodes
• Stabiles JSON und Problem-Details-Fehler
• Dokumentierte Filter, Sortierung und Pagination
• Authentifizierung, Autorisierung, Validierung und Rate Limits
• Kompatibilitäts- und Versionsstrategie
• OpenAPI, Contract-Tests und Observability

Häufige Fragen

Sollten URLs Verben enthalten?

Normalerweise nicht. Verwenden Sie Ressourcennamen und HTTP-Methoden. Ein echter Geschäftsbefehl kann als Ressource wie POST /orders/42/cancellation modelliert werden.

Was ist die wichtigste Regel?

Konsistenz. Eine vernünftige, überall angewandte Konvention ist leichter nutzbar als clevere Endpunkte mit unterschiedlichem Verhalten.