Was ist eine API? REST-API einfach erklärt

01Was ist eine API? Der Kellner-Vergleich

Der bekannteste Weg, was eine API ist zu erklären, ist der Restaurant-Vergleich. Sie sind der Gast, die Küche ist das System, das die Daten hält. In die Küche können Sie nicht selbst gehen; Sie sehen in die Speisekarte und geben die Bestellung beim Kellner auf. Der Kellner gibt den Wunsch an die Küche weiter und bringt Ihnen das fertige Gericht. In diesem Szenario ist der Kellner die API.

Auch die Speisekarte hat ihr Gegenstück in der API: die Dokumentation. Sie sagt, was Sie anfragen können, wie Sie es anfragen und was Sie dafür bekommen. Was nicht auf der Karte steht, können Sie nicht bestellen; wie die Küche arbeitet, müssen Sie aber auch nicht wissen.

In der Softwarewelt bringt diese Ordnung eine große Erleichterung. Ein Onlineshop muss das interne System des Paketdienstes nicht kennen; er sagt der API des Paketdienstes “erstelle ein Label für diese Sendung” und erhält die Antwort. Beide Seiten können ihren inneren Aufbau ändern, solange der API-Vertrag erhalten bleibt.

02Wozu dient eine API?

Die Antwort auf die Frage, wozu eine API dient, steckt in fast jedem digitalen Dienst, den Sie täglich nutzen. Auf einer Website einen Standort auf der Karte auswählen, per Karte bezahlen, sich mit Google anmelden oder das Wetter ansehen: Im Hintergrund ist das ein API-Aufruf.

• Sie verbindet Systeme: Website, Marktplatz, Versand, Buchhaltung und Zahlungssysteme arbeiten in einem Fluss.
• Sie verringert manuelle Dateneingabe: Bestell-, Bestands- und Rechnungsdaten gehen von selbst von einem System ins andere über.
• Sie speist mobile Apps: Die App auf dem Telefon holt Daten nicht direkt aus der Datenbank, sondern über die API.
• Sie ermöglicht die Nutzung fertiger Dienste: Zahlungs-, Karten-, SMS- oder E-Mail-Infrastruktur muss nicht von Grund auf geschrieben werden.
• Sie bietet sicheren Zugriff: Externen wird nicht die ganze Datenbank geöffnet, sondern nur die erlaubten Aktionen.

03Was ist eine REST-API?

APIs können in verschiedenen Stilen entworfen werden; im Web am weitesten verbreitet ist der REST-Ansatz. Die kurze Antwort auf die Frage, was eine REST-API ist: ein API-Stil, der das HTTP-Protokoll nutzt, jedes Datenelement über eine Adresse (Ressource) bestimmt und auf diesen Ressourcen mit Standardmethoden arbeitet.

In REST ist alles eine Ressource: Produkte, Bestellungen, Kunden. Jede Ressource hat eine Adresse, und mit welcher HTTP-Methode Sie diese Adresse aufrufen, bestimmt, was Sie tun wollen. Die Antworten kommen meist im JSON-Format zurück, einem Textformat, das sowohl für Menschen lesbar als auch für Programme leicht zu verarbeiten ist.

Was ist ein Endpoint?

Ein Endpoint (Endpunkt) ist die Adresse in einer API, unter der eine bestimmte Aktion ausgeführt wird. Zum Beispiel ist /api/urunler der Endpoint für die Produktliste und /api/urunler/42 der für das Produkt mit der Nummer 42. Eine API-Dokumentation ist im Grunde die Liste dieser Endpoints, der Methoden, mit denen sie aufgerufen werden, und dessen, was sie zurückgeben.

Statuscodes

Mit jeder Antwort kommt ein HTTP-Statuscode, der das Ergebnis der Aktion zusammenfasst. 200 bedeutet erfolgreich, 201 Datensatz erstellt, 400 fehlerhafte Anfrage, 401 nicht authentifiziert, 403 keine Berechtigung, 404 nicht gefunden, 429 zu viele Anfragen und 500 Serverfehler. Eine gute Integration behandelt jeden Code gesondert.

04Wie sieht eine API-Anfrage aus?

Eine API-Anfrage besteht im Kern aus vier Teilen: der Adresse, der Methode, den Headern (Zugangsdaten, Datentyp) und, falls nötig, dem Body (den gesendeten Daten). Unten sehen Sie eine einfache Leseanfrage an eine öffentliche Test-API und eine typische JSON-Antwort.

Diese Anfrage lässt sich im Terminal mit curl, im Browser mit JavaScript oder auf dem Server mit Python oder Node.js senden; die Regeln sind dieselben, nur das verwendete Werkzeug ändert sich.

curl -s https://jsonplaceholder.typicode.com/posts/1 \
  -H "Accept: application/json"

{
  "userId": 1,
  "id": 1,
  "title": "...",
  "body": "..."
}

const yanit = await fetch("https://jsonplaceholder.typicode.com/posts/1");
if (!yanit.ok) throw new Error(`Hata: ${yanit.status}`);
const veri = await yanit.json();
console.log(veri.title);

05API-Sicherheit und Authentifizierung

Außer bei öffentlichen Test-APIs kommen Sie an eine echte API nicht heran, ohne zu beweisen, wer Sie sind. Die gängigsten Verfahren sind der API-Schlüssel, kurzlebige Zugriffstoken und Autorisierungsabläufe wie OAuth.

Sicherheit besteht nicht nur aus Authentifizierung. Eine gut gestaltete API gibt jedem Nutzer nur so viele Rechte wie nötig, validiert eingehende Daten und begrenzt die Zahl der Anfragen, um Missbrauch zu verhindern (Rate Limit).

• Legen Sie API-Schlüssel niemals in Code, der an den Browser geht, oder in ein öffentliches Repository.
• Bauen Sie die Verbindung immer über HTTPS auf.
• Bewahren Sie Schlüssel in Umgebungsvariablen auf und erneuern Sie sie in regelmäßigen Abständen.
• Fordern Sie nur die nötigen Berechtigungen an; verlangen Sie keine Schreibrechte, wenn Leserechte genügen.
• Geben Sie in Fehlerantworten keine internen Systemdetails preis.

06Beispiele für API-Integrationen

Eine API-Integration verbindet zwei oder mehr Systeme so, dass sie über APIs regelmäßig und automatisch Daten austauschen. Im Tagesablauf eines E-Commerce-Unternehmens begegnen einem fast alle diese Verbindungen.

Geht eine Bestellung ein, wird der Bestand in allen Kanälen aktualisiert, in denen das Produkt verkauft wird; das leistet die Marktplatz-Anbindung. Wird die Bestellung bestätigt, werden Label und Sendungsnummer vom Paketdienst abgeholt; dieser Schritt gehört zur Versand-Anbindung. Die Rechnung wird dagegen mit der E-Rechnung-Integration (E-Rechnung ist das türkische E-Rechnungssystem) automatisch erstellt und dem Kunden übermittelt.

Bei all diesen Verbindungen ist nicht der erste Aufruf der schwierige Teil. Fragen wie: Was passiert, wenn das Gegensystem nicht antwortet? Wie verhindert man, dass dieselbe Bestellung zweimal verarbeitet wird? Wer wird bei einem Fehler benachrichtigt? Die Antworten darauf machen den Unterschied zwischen einer soliden Integration und einer fragilen Verbindung.

API oder Webhook?

Bei einer API fragen Sie, und die Gegenseite antwortet. Bei einem Webhook meldet sich die Gegenseite von selbst bei Ihnen, wenn ein Ereignis eintritt. Statt ständig zu fragen “gibt es eine neue Bestellung?”, ist es oft effizienter, bei einer Bestellung benachrichtigt zu werden; Details im Beitrag Was ist ein Webhook.

07Wo fängt man mit der API-Entwicklung an?

Um den Umgang mit APIs zu lernen, ist es ein guter Anfang, eine öffentliche Test-API auszuwählen und Anfragen mit curl oder einem API-Testwerkzeug zu senden. Antworten lesen, Statuscodes deuten und Fehlerfälle ausprobieren festigt die Konzepte schnell.

Wenn Sie eine eigene API schreiben möchten, müssen Sie eine Backend-Sprache wählen. Für einen schnellen, gut lesbaren Einstieg schauen Sie sich das FastAPI-Beispiel im Beitrag Was ist Python an, und wenn Sie mit JavaScript weitermachen möchten, das Express-Beispiel im Beitrag Was ist Node.js.

In jedem Fall hat eine gute API drei Gemeinsamkeiten: eine klare und aktuelle Dokumentation, konsistente Benennung und vorhersehbare Fehlerantworten. Wenn ein Entwickler, der die API nutzen will, die Dokumentation lesen und in wenigen Minuten seine erste Anfrage absetzen kann, ist das Design auf dem richtigen Weg.