Was ist ein API-Endpoint? Definition, Beispiele, Best Practices

Was ist ein API-Endpoint?

Ein API-Endpoint (auch API-Endpunkt) ist die Adresse, die ein Client aufruft, um genau eine Operation einer API zu nutzen: ein URL-Pfad in Kombination mit einer HTTP-Methode, zum Beispiel GET /users/42, um einen Nutzer zu lesen, oder POST /users, um einen anzulegen. Derselbe Pfad mit einer anderen Methode ist ein anderer Endpoint. Alle Endpoints zusammen bilden die Oberfläche der API.

REST-APIs bieten viele Endpoints, meist einen pro Ressource und Operation. GraphQL hat in der Regel nur einen Endpoint (oft /graphql); der Client beschreibt im Request, welche Daten er braucht. gRPC benennt Operationen als Methoden eines Dienstes statt als URL-Pfade.

So funktioniert ein API-Endpoint

Ein REST-Endpoint besteht aus drei Teilen:

• Basis-URL. Protokoll, Host und optionaler Präfix, zum Beispiel https://api.example.com.
• Pfad. Die Route zu einer Ressource, zum Beispiel /users/42. Query-Parameter wie ?page=2&limit=20 verfeinern sie.
• HTTP-Methode. Das Verb, das die Operation festlegt: GET, POST, PUT, PATCH oder DELETE.

Ein vollständiger Aufruf eines Endpoints zum Anlegen eines Nutzers samt Antwort:

POST https://api.example.com/users
Content-Type: application/json
Authorization: Bearer <token>

{ "name": "Alice", "email": "alice@example.com" }

HTTP/1.1 201 Created
Location: /users/43

Die Methode ist mehr als ein Name. Laut MDN ist nur GET "safe" (verändert nichts auf dem Server), und GET, PUT und DELETE sind idempotent: Wiederholen hat dieselbe Wirkung wie ein einmaliger Aufruf. POST und PATCH sind nicht idempotent, deshalb brauchen Wiederholungen dort Vorsicht, siehe Idempotenz.

Typische Endpoint-Muster

Design-Regeln, die sich bewährt haben

• Substantive im Pfad, Verben in der Methode. /users, nicht /getUsers.
• Ein einheitlicher Stil. Plural oder Singular, kebab-case oder snake_case: einmal entscheiden und überall gleich anwenden.
• Pfade, die Beziehungen zeigen. /users/42/orders liest sich als "die Bestellungen von Nutzer 42".
• Echte Statuscodes. 201 nach dem Anlegen, 204 für eine leere Erfolgsantwort, 400 für eine fehlerhafte Anfrage, 401 ohne Authentifizierung, 403 ohne Berechtigung, 404 wenn nichts gefunden wird, 429 bei zu vielen Anfragen, 5xx für Serverfehler (MDN, basierend auf RFC 9110).
• Paginierung und Filter im Query-String. /users?role=admin&page=2.
• Explizite Versionen. Mit /v1/users lassen sich Breaking Changes als /v2 ausliefern.
• Eine maschinenlesbare Spezifikation. Beschreiben Sie jeden Endpoint in OpenAPI, siehe Was ist Swagger.

Häufige Endpoint-Fehler

• Aktionen im Pfad. POST /createUser und ?action=delete widersprechen der Semantik der Methoden. Besser: POST /users und DELETE /users/42.
• HTTP 200 mit Fehler im Body. Clients, Caches und Monitoring lesen zuerst den Statuscode. Für Fehler gehören 4xx oder 5xx zurück.
• Geheimnisse in der URL. Tokens und personenbezogene Daten in Pfad oder Query-String landen in Logs, Browserverlauf und Referrern. Senden Sie sie im Header oder Body.
• Uneinheitliches Fehlerformat. Liefert ein Endpoint {"error": ...} und ein anderer {"message": ...}, braucht jeder Client Sonderfälle.
• Keine Autorisierungsprüfung pro Endpoint. Authentifizierung sagt, wer anfragt. Jeder Endpoint muss trotzdem prüfen, was diese Person darf.
• Kein Rate Limit. Ein unbegrenzter Endpoint fällt bei Missbrauch oder Retry-Stürmen als Erster um. Antworten Sie mit 429 und einem Retry-After-Header. Hintergrund: Ursachen für API-Rate-Limiting (Artikel auf Englisch).

API-Endpoints testen und überwachen

Jeder Endpoint lässt sich auf mehreren Ebenen prüfen. API-Tests stellen sicher, dass Daten und Statuscode stimmen. Lasttests zeigen, wie sich der Endpoint verhält, wenn viele Clients gleichzeitig zugreifen; LoadFocus führt JMeter- und k6-Tests aus 25 Cloud-Regionen aus, der kostenlose Tarif umfasst bis zu 10 virtuelle Nutzer. Ist der Endpoint live, ruft API-Monitoring ihn nach Zeitplan auf und prüft Statuscode, Body, Header und Antwortzeit, sodass auch ein 200 mit falschem Inhalt als Fehler zählt; der kostenlose Tarif prüft alle 5 Minuten. Für einen schnellen Blick auf eine öffentliche URL sendet der API-Status-Checker ohne Anmeldung eine Anfrage aus sechs Regionen. Typische Ursachen langsamer Endpoints beschreibt Common API performance issues and how to detect them (auf Englisch), die Überwachung erklärt Was ist API-Monitoring.

Häufige Fragen zu API-Endpoints

Was ist der Unterschied zwischen einer API und einem API-Endpoint?

Die API ist die gesamte Schnittstelle: alle Endpoints samt Schemas, Authentifizierung und Fehlerformaten. Ein Endpoint ist eine einzelne Operation darin, etwa der Aufruf zum Erstellen einer Zahlung in einer Payment-API.

Sind GET /users und POST /users derselbe Endpoint?

Nein. Sie teilen sich den Pfad, nutzen aber verschiedene Methoden und sind damit zwei Endpoints: einer listet Nutzer auf, der andere legt einen an.

Ist ein Endpoint dasselbe wie eine URL?

Nicht ganz. Die URL ist nur die Adresse. Der Endpoint ist die URL plus die HTTP-Methode, denn die Methode entscheidet, was der Server tut.

Wie viele Endpoints sollte eine API haben?

So viele, wie ihr Umfang verlangt. Eine kleine, fokussierte API hat vielleicht eine Handvoll, eine große Plattform-API Hunderte. Die Anzahl sagt nichts über die Qualität; Einheitlichkeit und gute Dokumentation tun es.

Wie unterscheiden sich REST- und GraphQL-Endpoints?

REST verteilt Operationen auf viele Endpoints, je einen pro Ressource und Methode. GraphQL hat meist einen Endpoint, und die Abfrage im Request legt fest, welche Felder zurückkommen.

Wie ändere ich einen Endpoint, ohne Clients zu brechen?

Versionieren Sie den Pfad (/v1/users, /v2/users), betreiben Sie beide Versionen während der Übergangszeit, nennen Sie ein Abschaltdatum für die alte und dokumentieren Sie die Änderungen.