REST API DESIGN: BEST PRACTICES FÜR SAUBERE SCHNITTSTELLEN

Warum API-Design wichtig ist

Eine API ist die Schnittstelle zwischen Systemen – und zwischen Teams. Schlechtes API-Design führt zu:

Verwirrten Frontend-Entwicklern
Inkonsistentem Verhalten
Schwieriger Wartung
Integrationsproblemen mit Drittanbietern

Gutes API-Design hingegen macht die Integration intuitiv und reduziert Support-Aufwand.

Die Grundprinzipien

1. Ressourcen-orientiert denken

REST dreht sich um Ressourcen, nicht um Aktionen. Eine Ressource ist ein Ding (User, Produkt, Bestellung), keine Aktion.

# Falsch - aktionsorientiert
POST /createUser
GET /getUserById?id=123
POST /deleteUser

# Richtig - ressourcenorientiert
POST /users
GET /users/123
DELETE /users/123

2. HTTP-Methoden richtig nutzen

| Methode | Zweck | Beispiel |

|---------|-------|----------|

| GET | Lesen | GET /users/123 |

| POST | Erstellen | POST /users |

| PUT | Vollständig ersetzen | PUT /users/123 |

| PATCH | Teilweise aktualisieren | PATCH /users/123 |

| DELETE | Löschen | DELETE /users/123 |

// GET - Daten abrufen (keine Seiteneffekte!)
GET /products?category=electronics&limit=10

// POST - Neue Ressource erstellen
POST /orders
Body: { "productId": 123, "quantity": 2 }

// PATCH - Teilweise aktualisieren
PATCH /users/123
Body: { "email": "new@example.com" }

// DELETE - Ressource löschen
DELETE /orders/456

3. Sinnvolle URL-Struktur

# Plural für Collections
GET /users           # Alle User
GET /users/123       # Ein User

# Verschachtelte Ressourcen
GET /users/123/orders          # Bestellungen eines Users
GET /users/123/orders/456      # Eine spezifische Bestellung

# Maximal 2-3 Ebenen tief
GET /users/123/orders/456/items  # Noch OK
GET /users/123/orders/456/items/789/details  # Zu tief!

HTTP-Statuscodes richtig einsetzen

Erfolg (2xx)

200 OK              - Erfolgreiche GET, PUT, PATCH Anfrage
201 Created         - Ressource erfolgreich erstellt (POST)
204 No Content      - Erfolg ohne Response-Body (DELETE)

Client-Fehler (4xx)

400 Bad Request     - Ungültige Anfrage (Validierungsfehler)
401 Unauthorized    - Nicht authentifiziert
403 Forbidden       - Authentifiziert, aber keine Berechtigung
404 Not Found       - Ressource existiert nicht
409 Conflict        - Konflikt (z.B. Duplikat)
422 Unprocessable   - Validierung fehlgeschlagen

Server-Fehler (5xx)

500 Internal Error  - Unerwarteter Serverfehler
503 Service Unavailable - Server temporär nicht verfügbar

Response-Struktur

Konsistente Envelope

// Erfolg
{
  "data": {
    "id": 123,
    "name": "Max Mustermann",
    "email": "max@example.com"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

// Fehler
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

Pagination

GET /users?page=2&limit=20

{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "links": {
    "first": "/users?page=1&limit=20",
    "prev": "/users?page=1&limit=20",
    "next": "/users?page=3&limit=20",
    "last": "/users?page=8&limit=20"
  }
}

Filtering, Sorting, Suche

Filtering

# Einfache Filter als Query-Parameter
GET /products?category=electronics
GET /products?minPrice=100&maxPrice=500
GET /products?inStock=true

# Multiple Werte
GET /products?category=electronics,books

Sorting

# Aufsteigend
GET /products?sort=price

# Absteigend (Minus-Präfix)
GET /products?sort=-price

# Multiple Felder
GET /products?sort=-createdAt,name

Suche

# Einfache Suche
GET /products?search=laptop

# Feld-spezifische Suche
GET /products?name_contains=Pro&brand=Apple

Versionierung

URL-Versionierung (empfohlen)

GET /v1/users
GET /v2/users

Vorteile:

Klar sichtbar
Einfach zu testen
Cache-freundlich

Header-Versionierung

GET /users
Accept: application/vnd.api+json;version=2

Authentifizierung

Bearer Token (JWT)

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Keys

# Im Header (bevorzugt)
X-API-Key: your-api-key

# Oder als Query-Parameter (weniger sicher)
GET /users?api_key=your-api-key

Praktisches Beispiel

Eine vollständige User-API:

// GET /v1/users - Liste aller User
// Query: ?page=1&limit=20&sort=-createdAt&role=admin
{
  "data": [
    { "id": 1, "name": "Max", "email": "max@example.com", "role": "admin" },
    { "id": 2, "name": "Anna", "email": "anna@example.com", "role": "admin" }
  ],
  "meta": { "page": 1, "limit": 20, "total": 2 }
}

// GET /v1/users/1 - Einzelner User
{
  "data": {
    "id": 1,
    "name": "Max",
    "email": "max@example.com",
    "role": "admin",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

// POST /v1/users - User erstellen
// Request:
{ "name": "Neu", "email": "neu@example.com", "password": "secret123" }
// Response (201 Created):
{
  "data": { "id": 3, "name": "Neu", "email": "neu@example.com" }
}

// PATCH /v1/users/1 - User aktualisieren
// Request:
{ "name": "Max Updated" }
// Response (200 OK):
{
  "data": { "id": 1, "name": "Max Updated", "email": "max@example.com" }
}

// DELETE /v1/users/1 - User löschen
// Response: 204 No Content

Checkliste für gutes API-Design

[ ] Ressourcen-orientierte URLs (Nomen, nicht Verben)
[ ] Korrekte HTTP-Methoden (GET, POST, PUT, PATCH, DELETE)
[ ] Sinnvolle HTTP-Statuscodes
[ ] Konsistente Response-Struktur
[ ] Pagination für Listen
[ ] Filtering und Sorting
[ ] Versionierung
[ ] Authentifizierung
[ ] Rate Limiting
[ ] Dokumentation (OpenAPI/Swagger)

Fazit

Gutes API-Design ist keine Raketenwissenschaft, aber es erfordert Disziplin. Die wichtigsten Regeln:

1. Konsistenz: Wenn /users so funktioniert, sollte /products genauso funktionieren

2. Vorhersehbarkeit: Entwickler sollten erraten können, wie ein Endpoint funktioniert

3. Dokumentation: Auch die beste API braucht gute Docs