Konventionen von URLs, Methoden und Fehlern: vorhersagbare und standardisierte APIs

Zuletzt aktualisiert:

Diana Romanova

—

Juni 25, 2025

URL Konventionen, Methoden, Fehler ('GET', 'POST', 'PUT', 'DELETE')

Eine zuverlässige und verständliche API beginnt mit klaren Regeln für den Aufbau von Schnittstellen. Wir halten uns an die Best Practices von REST, damit jeder Entwickler weiß, was ihn erwartet: Die URL-Struktur ist logisch, die Methoden entsprechen der Aktion und Fehler sind leicht zu interpretieren.

Dies senkt die Einstiegsschwelle, vereinfacht die Integration und ermöglicht eine Systemskalierung ohne Chaos.

URL- und HTTP-Methodenkonventionen

Methode	Die Bestimmung	Beispiel für eine Abfrage
`GET`	Abrufen einer Ressource	`GET /users/42`
`POST`	Erstellen einer neuen Ressource	`POST /users`
`PUT`	Vollständige Aktualisierung der Ressource	`PUT /users/42`
`PATCH`	Teilweise Aktualisierung der Ressource (Opz.) `PATCH /users/42`
`DELETE`	Löschen einer Ressource	`DELETE /users/42`

Substantive im Plural werden verwendet ('/users', '/devices', '/games')

Verschachtelte Entitäten werden als Hierarchie beschrieben ('/users/42/sessions')
Alle Anfragen laufen über HTTPS

Standards für die Fehlerbehandlung

Kode	Die Bedeutung	Beispiel für eine Nachricht
`400`	Falsche Anfrage	`Missing required field: email`
`401`	neawtorisowan	`Invalid token or expired session`
`403`	Zugang verboten	`Access denied to resource`
`404`	Nicht gefunden	`User with ID 42 not found`
`409`	Konflikt (z.B. Duplizierung)	`Email already in use`
`422`	Validierungsfehler	`Field 'age' must be a number`
`500`	Interner Serverfehler	`Unexpected exception, contact support`

Struktur der Fehlerantwort:

json
{
"error": {
"code": 400,   "message": "Missing required field: email",   "details": {...}
}
}

Vorteile für Entwickler

Schnelles Verständnis der API-Logik ohne unnötige Dokumentation

Einheitlicher Ansatz für alle Module und Entitäten
Einfaches Debuggen und Loggen dank Standardcodes und -formaten
Kompatibel mit OpenAPI/Swagger, Postman, Auto-Generierung SDK
Vereinfachte Unterstützung, Tests und CI/CD

Wo es besonders wichtig ist

Plattformen mit offener oder Partner-API

Projekte mit mehreren Entwicklungsteams
Microservices-Architektur oder API-erster Ansatz
Systeme mit einer großen Anzahl von Entitäten und Interaktionen

Einheitliche Konventionen machen APIs zuverlässig, verständlich und benutzerfreundlich. Wir halten uns an die besten REST-Praktiken, um sicherzustellen, dass jede Integration schnell, ohne Missverständnisse und mit maximaler Vorhersehbarkeit erfolgt.