Warum API-Design wichtig ist
Eine gut konzipierte API ist ein Produkt an sich. Sie beeinflusst die Entwicklererfahrung, die Integrationsgeschwindigkeit und die langfristige Wartbarkeit. Hier sind die Grundsätze, die wir bei DevFlow befolgen.
URL-Design-Grundsätze
Ressourcennamen
Verwenden Sie Nomen, nicht Verben. Die HTTP-Methode legt die Aktion fest.
# Gut
GET /api/v1/nutzer
POST /api/v1/nutzer
GET /api/v1/nutzer/:id
# Schlecht
GET /api/v1/erhalteNutzer
POST /api/v1/erstelleNutzerKonsistenter Antwortformat
Jeder API-Endpunkt sollte eine konsistente Format zurückgeben, damit die Verbraucher wissen, was sie erwarten können.
{
"status": "Erfolg",
"data": { "id": "nutzer-123", "name": "Hans Müller" },
"pagination": { "seite": 2, "limit": 20, "gesamt": 150 }
}HTTP-Statuscodes
| Code | Verwendung |
|---|---|
| 200 | Erfolgreiche GET, PUT, PATCH |
| 201 | Erfolgreiche POST (Ressource erstellt) |
| 204 | Erfolgreiche DELETE (keine Inhalte) |
| 400 | Validierungsfehler |
| 401 | Authentifizierung erforderlich |
| 403 | Unzureichende Berechtigungen |
| 404 | Ressource nicht gefunden |
| 429 | Überschreitung der Rate-Limits |
Pagination-Muster
# Cursor-basiert (empfohlen für große Datensätze)
GET /api/v1/beiträge?cursor=eyJpZCI6MTAwfQ&limit=20
# Offset-basiert (einfacher, gut für kleine Datensätze)
GET /api/v1/beiträge?page=3&limit=20Zusammenfassung
Ein gutes API-Design ist eine Investition, die sich während des gesamten Produktlebenszyklus auszahlt. Befolgen Sie Konventionen, seien Sie konsistent und dokumentieren Sie alles.
