# REST API Design: Architektur & Best Practices für skalierbare Schnittstellen

TL;DR / Management Summary Nahezu jede moderne Automatisierung (Proxmox API, OPNsense API) basiert auf REST (Representational State Transfer). REST ist kein Protokoll, sondern ein Architektur-Stil, der auf Standard-HTTP-Methoden und zustandsloser Kommunikation aufbaut. Ein Senior Admin versteht die Bedeutung von Ressourcen-basierten URLs, nutzt korrekte HTTP-Status-Codes zur Fehlerbehandlung und dokumentiert seine Schnittstellen via OpenAPI (Swagger), um die Integration in den DevOps-Stack zu vereinfachen.

# 1. Die goldenen Regeln des REST

Vom Endpunkt zur Ressource.

1. Alles ist eine Ressource: Nutzen Sie Substantive statt Verben in der URL.
   • Falsch: GET /get_all_vms
   • Richtig: GET /vms
2. Zustandslosigkeit (Stateless): Jeder Request muss alle Informationen enthalten, die der Server zum Verständnis braucht. Keine Session-Daten am Server speichern.
3. Standard HTTP Methoden nutzen.

# 2. HTTP Methoden & Semantik

Das Vokabular der API.

• GET: Ressource abrufen (darf keine Daten ändern!).
• POST: Neue Ressource erstellen.
• PUT: Bestehende Ressource komplett ersetzen.
• PATCH: Bestehende Ressource teilweise ändern (z.B. nur den RAM einer VM).
• DELETE: Ressource löschen.

# 3. Deep Dive: HTTP Status Codes

Die Antwort des Servers.

Nutzen Sie die standardisierten Bereiche:

• 200 OK: Alles geklappt.
• 201 Created: Ressource erfolgreich angelegt (nach POST).
• 400 Bad Request: Fehler im JSON des Clients.
• 401 Unauthorized: Token fehlt oder ist ungültig (Artikel 712).
• 403 Forbidden: Token gültig, aber keine Rechte für diesen Pfad.
• 404 Not Found: Ressource (z.B. VM-ID) existiert nicht.
• 500 Internal Server Error: Bug am Server.

# 4. Day-2 Operations: Dokumentation mit OpenAPI

Der Vertrag zwischen Dev und Ops.

Nutzen Sie OpenAPI (früher Swagger) zur Beschreibung Ihrer API.

• Vorteil: Erzeugt automatisch interaktive Web-Dokumentationen.
• Vorteil: Erlaubt die automatische Generierung von Client-Bibliotheken (SDKs) in Python oder Go.

# 5. Troubleshooting & “War Stories”

Wenn die Schnittstelle schweigt.

# Top 3 Fehlerbilder

1. Symptom: “Method Not Allowed” (405).

   • Ursache: Sie versuchen ein POST auf einen Endpunkt, der nur GET erlaubt.
   • Lösung: API-Viewer (Artikel 699) prüfen.

2. Symptom: API-Antworten sind inkonsistent (mal JSON, mal HTML).

   • Ursache: Falscher Accept Header im Request.
   • Fix: Erzwingen Sie Accept: application/json.

3. Symptom: Performance-Probleme bei Massenabfragen.

   • Lösung: Implementieren Sie Pagination (?limit=100&offset=0).

# “War Story”: Der “Idempotenz”-Fehler

Ein Admin schrieb ein Skript, das via POST neue VMs anlegte. Das Ereignis: Das Skript lief in einen Timeout, bevor die Bestätigung kam. Das Skript startete einen Retry. Das Ergebnis: Da der POST Befehl nicht idempotent ist (jeder Aufruf erstellt eine neue Ressource), hatte der Admin am Ende drei identische VMs in Proxmox, statt einer. Lehre: Nutzen Sie für Änderungen nach Möglichkeit PUT oder PATCH, da diese laut Standard idempotent sein müssen (mehrfache Ausführung hat das gleiche Ergebnis). Nutzen Sie bei POST eindeutige Client-Token (Idempotency-Keys).

# 6. Monitoring & Reporting

API-Analytics.

# API Dashboard (Kibana)

Analysieren Sie Ihre API-Logs (Artikel 819):

• Distribution of HTTP Status Codes.
• Slowest API Endpoints.
• Most Active API Users.

# 7. Fazit & Empfehlung

Gutes API-Design ist der Schlüssel zur erfolgreichen Automatisierung.

• Empfehlung: Nutzen Sie JSON als ausschließliches Datenformat. XML ist im modernen Cloud-Umfeld veraltet.
• Wichtig: Implementieren Sie von Anfang an eine Versionierung in der URL (z.B. /api/v1/vms), damit Sie später Änderungen einführen können, ohne bestehende Skripte zu brechen.

# Anhang: Cheatsheet (REST Patterns)

# Referenzen

• Architectural Styles and the Design of Network-based Software Architectures (Roy Fielding)
• OpenAPI Specification (GitHub)
• Microsoft: RESTful API design Best Practices