In der heutigen vernetzten Welt sind REST-APIs das Rückgrat der modernen Softwarearchitektur und ermöglichen eine nahtlose Kommunikation zwischen Systemen. Namenskonventionen in REST-API spielen eine entscheidende Rolle bei der Gewährleistung von Klarheit, Konsistenz und Benutzerfreundlichkeit. Die gut gestaltete API ist intuitiv, einfach zu bedienen und hält sich an etablierte Standards. Hier finden Sie eine Kurzanleitung zu Benennungsstandards, die die Qualität Ihres API-Designs verbessern.
1. Verwenden Sie Substantive als Ressourcen, nicht als Verben
REST-APIs sind um Ressourcen herum konzipiert, die Entitäten in Ihrer Anwendung darstellen. Die Endpunktnamen sollten diese Ressourcen mithilfe von Substantiven und nicht mit Aktionen widerspiegeln.
Beispiel:
- ✅ (Gut: bezieht sich auf eine Sammlung von Benutzern)
/users - ❌ (Vermeiden: Verben wie „get“ werden von der HTTP-Methode impliziert)
/getUsers
Verwenden Sie für Aktionen, die nicht zu CRUD (Erstellen, Lesen, Aktualisieren, Löschen) passen, Unterressourcen oder eine aussagekräftigere Struktur:
- ✅ (Für eine bestimmte Aktion, z. B. das Aktivieren eines Benutzers)
/users/{id}/activate
2. Verwenden Sie Substantive im Plural
Verwenden Sie für Ressourcennamen immer Substantive im Plural, es sei denn, die Ressource ist von Natur aus singulär.
Beispiel:
- ✅ (Gut: eine Sammlung von Produkten)
/products - ❌ (Vermeiden: Die Pluralform spiegelt den Sammlungscharakter wider)
/product
Singularformen können für Unterressourcen oder bestimmte Identifikatoren verwendet werden:
/products/{id}(Zugriff auf ein einzelnes Produkt über die ID)
3. Halten Sie sich an Kleinbuchstaben und Bindestriche
URLs sollten immer klein geschrieben werden, um Verwirrung zu vermeiden, da bei einigen Systemen zwischen Groß- und Kleinschreibung unterschieden wird.
Verwenden Sie Bindestriche (), um Wörter zur besseren Lesbarkeit zu trennen, und vermeiden Sie Unterstriche ().-_
Beispiel:
- ✅ (Gut: Kleinbuchstaben und Bindestriche getrennt)
/order-items - ❌ (Vermeiden: Camel Case ist schwerer zu lesen)
/OrderItems - ❌ (Vermeiden: Unterstriche sind weniger benutzerfreundlich)
/order_items
4. Hierarchisch strukturieren
Organisieren Sie Ihre Endpunkte hierarchisch, um die Beziehung zwischen Ressourcen widerzuspiegeln.
Beispiel:
/users/{id}/orders(Bestellungen, die zu einem bestimmten Benutzer gehören)/products/{id}/reviews(Bewertungen für ein bestimmtes Produkt)
Vermeiden Sie das Erstellen tief verschachtelter Strukturen, da diese die Verwendung der API erschweren können:
- ❌ (Zu komplex)
/companies/{companyId}/departments/{departmentId}/employees/{employeeId}
Vereinfachen Sie stattdessen nach Möglichkeit Abfrageparameter:
- ✅
/employees?company={companyId}&department={departmentId}
5. Verwenden von Abfrageparametern zum Filtern und Sortieren
Verwenden Sie zum Filtern, Sortieren und Paginieren Abfrageparameter, anstatt neue Endpunkte zu erstellen.
Beispiel:
- ✅
/products?category=electronics&sort=price_desc&page=2
Vermeiden Sie Endpunkte wie:
- ❌
/products/electronics/price_desc/page2
6. Verwenden Sie Standard-HTTP-Methoden
Lassen Sie die HTTP-Methode die Aktion definieren, nicht den Endpunktnamen. Dies sorgt für Konsistenz und macht die API selbsterklärend.
7. Versionieren Sie Ihre REST-API
APIs entwickeln sich im Laufe der Zeit weiter, daher ist es wichtig, eine Version in Ihren Endpunktpfad aufzunehmen. Verwenden Sie die Hauptversionsnummer mit dem Präfix .v
Beispiel:
/api/v1/products
Vermeiden Sie das Einbetten von Versionen in Abfrageparameter oder Header:
- ❌
/api/products?version=1
8. Fehlerbehandlung und Antworten
Stellen Sie sicher, dass die Fehlerantworten einer Standardstruktur mit aussagekräftigen Fehlercodes und Meldungen folgen. Verwenden Sie geeignete HTTP-Statuscodes:
- 400: Ungültige Anfrage
- Nr. 401: Unbefugt
- Nr. 404: Ressource nicht gefunden
- 500: Interner Serverfehler
Beispiel für einen Antworttext:
{
"error": "Resource not found",
"details": "No product found with ID 1234"
}9. Halten Sie es konsistent
Konsistenz ist der Schlüssel zu einer großartigen API-Erfahrung. Sobald Sie Namenskonventionen festgelegt haben, halten Sie sich in Ihrer gesamten API an diese.
- Verwenden Sie immer die gleichen Begriffe und Formate für ähnliche Konzepte.
- Beispiel: Wenn Sie für eine einzelne Ressource verwenden, vermeiden Sie sie an anderer Stelle.
/users/{id}/user/{id}
10. Dokumentieren Sie alles
Eine gut benannte REST-API ist nur so gut wie ihre Dokumentation. Verwenden Sie Tools wie Swagger/OpenAPI, um eine klare und interaktive Dokumentation zu erstellen.
Die Namenskonventionen für REST-APIs mögen unbedeutend erscheinen, sind aber für die Erstellung einer benutzerfreundlichen und skalierbaren API unerlässlich. Die Übernahme dieser Best Practices stellt sicher, dass Ihre API intuitiv und einfach zu warten ist und für Entwickler angenehm zu bedienen ist.
Indem Sie sich auf Substantive, Konsistenz und Standards konzentrieren, erstellen Sie APIs, die Entwickler lieben und auf die sich die Benutzer verlassen können.
Weiterer Beitrag: API-Schlüssel vs. Token