6. Akzeptiere API-Schlüssel-Authentifizierung
Wenn eine API von einer dritten Partei aufgerufen werden muss, ist es sinnvoll, die Authentifizierung über API-Schlüssel zuzulassen. API-Schlüssel sollten mit einem benutzerdefinierten HTTP-Header (z. B. Api-Key) übergeben werden. Sie sollten ein Ablaufdatum haben, und es muss möglich sein, aktive Schlüssel zu widerrufen, damit sie ungültig gemacht werden können, falls sie kompromittiert werden. Vermeide das Einchecken von API-Schlüsseln in die Versionskontrolle (verwende stattdessen Umgebungsvariablen).
7. Verwende sinnvolle HTTP-Statuscodes
Verwende konventionelle HTTP-Statuscodes, um den Erfolg oder Misserfolg einer Anfrage anzuzeigen. Verwende nicht zu viele, und verwende in der gesamten API dieselben Statuscodes für dieselben Ergebnisse. Einige Beispiele:
- 200 für allgemeinen Erfolg
- 201 für eine erfolgreiche Erstellung
- 400 für fehlerhafte Anfragen vom Client
- 401 für nicht autorisierte Anfragen
- 403 für fehlende Berechtigungen
- 404 für fehlende Ressourcen
- 429 für zu viele Anfragen
- 5xx für interne Fehler (diese sollten auf jeden Fall vermieden werden)
8. Verwende sinnvolle HTTP-Methoden
Es gibt viele HTTP-Methoden, aber die wichtigsten sind:
- POST für die Erstellung von Ressourcen, z.B. POST /users
- GET zum Lesen von Ressourcen (sowohl einzelne Ressourcen als auch Sammlungen), z.B. GET /users, GET /users/{id}
- PATCH für die Anwendung teilweiser Aktualisierungen auf eine Ressource, z.B. PATCH /users/{id}
- PUT für die Anwendung vollständiger Aktualisierungen auf eine Ressource (ersetzt die aktuelle Ressource), z.B. PUT /users/{id}
- DELETE für das Löschen von Ressourcen, z.B. DELETE /users/{id}
9. Verwende selbsterklärende, einfache Namen
Die meisten Endpunkte sind resourcenorientiert und sollten dementsprechend benannt werden. Füge keine unnötigen Informationen hinzu, die von anderer Stelle abgeleitet werden können. Dies gilt auch für Feldnamen.
+++ GUT
GET /users => Abrufen von Benutzern
DELETE /users/{id} => Löschen eines Benutzers
POST /users/{id}/notifications => Erstellen einer Benachrichtigung für einen bestimmten Benutzer
users.first_name
orders.nummer
— SCHLECHT
GET /getUser
POST /updateUser
POST /notification/user
users.firstName
orders.ordernumber
10. Verwende standardisierte Fehlerantworten
Abgesehen von der Verwendung von HTTP-Statuscodes, die das Ergebnis der Anfrage (Erfolg oder Fehler) angeben, sollte bei der Rückgabe von Fehlern immer eine standardisierte Fehlerantwort verwendet werden, die genauere Informationen darüber enthält, was passiert ist Die Anwender können immer die gleiche Struktur erwarten und sich entsprechend verhalten.
// Request => GET /users/4TL011ax
// Response <= 404 Not Found
{
"code": "user/not_found",
"message": "A user with the ID 4TL011ax could not be found."
}
// Request => POST /users
{
"name": "John Doe"
}
// Response <= 400 Bad Request
{
"code": "user/email_required",
"message": "The parameter [email] is required."
}