Wenn man eine API von Grund auf neu erstellt, muss man viele Details beachten. Von grundlegenden Sicherheitsüberlegungen bis hin zur Verwendung der richtigen HTTP-Methoden, der Implementierung von Authentifizierung, der Entscheidung, welche Anfragen und Antworten man akzeptiert und zurückgeben sollte, … die Liste ist endlos.
In diesem Beitrag wird versucht, die Punkte zu betrachten, die nützlich sein können, um eine gute API zu entwicklen. Eine API, die gerne benutzt wird. Alle Tipps sind sprachunabhängig und gelten daher für jedes Framework und jede Technologie.
1. Sei konsequent
Es klingt logisch, aber es ist schwer, dies richtig zu machen. Die besten APIs, sind vorhersehbar. Wenn ein Anwender einen Endpunkt verwendet und versteht, kann er erwarten, dass ein anderer Endpunkt auf die gleiche Weise funktioniert. Dies ist wichtig für die gesamte API und einer der wichtigsten Indikatoren dafür, ob eine API gut konzipiert und benutzerfreundlich ist oder nicht.
- Verwende die gleiche Schreibweise für Felder, Ressourcen und Parameter (z.B. snake_case)
- Verwende entweder Plural- oder Singular-Ressourcennamen, z.B. /users/{id}, /orders/{id} oder /user/{id}, /order/{id}
- Verwende die gleichen Authentifizierungs- und Autorisierungsmethoden für alle Endpunkte
- Verwende die gleichen HTTP-Header für die gesamte API, z.B. „Api-Key“ für die Übergabe eines API-Schlüssels
- Verwendung der gleichen HTTP-Statuscodes je nach Art der Antwort, z.B. 404, wenn eine Ressource nicht gefunden werden kann
- Verwende dieselben HTTP-Methoden für dieselbe Art von Aktionen, z.B. DELETE, wenn eine Ressource gelöscht wird
2. Verwende ISO 8601 UTC-Daten
Wenn es um Datum und Uhrzeit geht, sollten APIs immer ISO 8601-formatierte Zeichenketten zurückgeben. Die Anzeige von Daten in einer bestimmten Zeitzone ist im Allgemeinen ein Anliegen von Client-Anwendungen.
{
"published_at": "2022-03-03T21:59:08Z"
}
3. Mache eine Ausnahme für öffentliche Endpunkte
Jeder Endpunkt sollte standardmäßig eine Autorisierung erfordern. Die meisten Endpunkte erfordern einen authentifizierten Benutzer, um aufgerufen zu werden, daher ist es sinnvoll, dies als Standard festzulegen. Wenn ein Endpunkt öffentlich aufgerufen werden muss, setze diesen Endpunkt explizit so, dass er nicht autorisierte Anfragen zulässt.
4. Stelle einen Endpunkt für einen health check bereit
Stelle einen Endpunkt bereit (z. B. GET /health), der feststellt, ob ein Dienst in Ordnung ist oder nicht. Dieser Endpunkt kann von anderen Anwendungen wie z. B. Load Balancern aufgerufen werden, um im Falle eines Serviceausfalls zu handeln.
5. Versioniere die API
Stelle sicher, dass die API versioniert und die Version bei jeder Anfrage weitergeben wird, damit die Anwender nicht von Änderungen an einer anderen Version betroffen sind. API-Versionen können mit HTTP-Headern oder Abfrage-/Pfadparametern übergeben werden. Selbst die erste Version der API (1.0) sollte explizit versioniert werden.
Beispiele:
https://api.averagecompany.com/v1/health
https://api.averagecompany.com/health?api_version=1.0 https://r.bluethl.net/how-to-design-better-apis
Quelle: Artikel in Ronald Blüthl’s Blog