Was ist eine API? Einfach erklärt für Einsteiger

Eine API sorgt dafür, dass Programme, Apps und Onlinedienste auf festgelegte Weise miteinander kommunizieren können. Ein Programm stellt eine Anfrage, die API nimmt sie entgegen und liefert Daten zurück oder führt eine bestimmte Aktion aus. Der Nutzer bekommt von diesem Austausch meist nichts mit.

Das passiert beispielsweise, wenn eine App Wetterdaten abruft, ein Onlineshop einen Zahlungsdienst einbindet oder eine Anwendung Informationen aus einem anderen Onlinedienst übernimmt. Dabei muss die aufrufende Software nicht wissen, wie das andere System intern aufgebaut ist.

API steht für „Application Programming Interface“, auf Deutsch meist „Programmierschnittstelle“ oder „Anwendungsprogrammierschnittstelle“. Hinter diesem Begriff steckt also kein einzelnes Programm, sondern eine klar definierte Möglichkeit, auf Funktionen oder Daten eines anderen Systems zuzugreifen.

Was ist eine API genau?

Eine API beschreibt, welche Funktionen ein Programm bereitstellt und wie andere Programme darauf zugreifen dürfen. Dazu gehören beispielsweise erlaubte Befehle, benötigte Angaben und das Format der zurückgegebenen Daten.

Das lässt sich mit einer normalen Programmfunktion vergleichen. Eine Funktion erwartet bestimmte Eingaben und liefert ein Ergebnis. Bei einer Web-API findet dieser Austausch allerdings häufig zwischen zwei getrennten Systemen über ein Netzwerk statt.

Ein typisches Beispiel ist eine Wetter-App. Sie muss Wetterdaten nicht selbst messen. Stattdessen sendet sie eine Anfrage an einen Wetterdienst. Dessen API liefert beispielsweise Temperatur, Luftfeuchtigkeit und Wetterzustand zurück. Die App bereitet diese Daten anschließend für den Nutzer auf.

APIs gibt es allerdings nicht ausschließlich im Internet. Auch Betriebssysteme, Programmbibliotheken und Webbrowser stellen Programmierschnittstellen bereit. Ein Programm kann darüber beispielsweise Dateien öffnen, auf Hardware zugreifen oder Funktionen des Browsers verwenden.

Wenn im Zusammenhang mit Webseiten und Onlinediensten von einer API gesprochen wird, ist häufig eine Web-API gemeint. Auf diese Form konzentriert sich der folgende Einsteiger-Guide.

Wie funktioniert eine API?

Bei einer typischen Web-API gibt es zwei Seiten: den Client und den Server. Der Client kann eine App, ein Programm oder ein anderes Serversystem sein. Er stellt eine Anfrage an die API des Servers.

Der Ablauf besteht vereinfacht aus vier Schritten:

1. Der Client sendet eine Anfrage an eine bestimmte Adresse der API.
2. Der Server prüft die Anfrage und gegebenenfalls die Zugriffsberechtigung.
3. Der Server verarbeitet die gewünschte Aktion.
4. Die API liefert eine Antwort an den Client zurück.

Eine solche Anfrage wird häufig als Request bezeichnet, die Antwort als Response.

Angenommen, eine Anwendung möchte Informationen über einen Benutzer mit der ID 25 abrufen. Eine REST-API könnte dafür beispielsweise einen Endpunkt nach diesem Muster bereitstellen:

https://api.example.com/users/25

Die Adresse bezeichnet den gewünschten Datensatz beziehungsweise die gewünschte Ressource. Der Server könnte daraufhin eine Antwort in diesem Format liefern:

{
  "id": 25,
  "name": "Max Mustermann",
  "status": "aktiv"
}

JSON ist eines der häufigsten Datenformate bei Web-APIs. Die Struktur lässt sich von Programmen leicht verarbeiten und bleibt gleichzeitig für Menschen relativ gut lesbar.

Endpoint, Request und Response: wichtige API-Begriffe

Wer zum ersten Mal mit einer API arbeitet, trifft schnell auf einige Begriffe, die komplizierter klingen, als sie sind.

Endpoint

Ein Endpoint oder Endpunkt bezeichnet eine Adresse, unter der eine bestimmte API-Funktion erreichbar ist.

Eine Benutzerverwaltung könnte beispielsweise verschiedene Endpunkte für Benutzer, Gruppen und Einstellungen bereitstellen. Welche Endpunkte vorhanden sind und welche Angaben sie erwarten, steht normalerweise in der API-Dokumentation.

Request

Der Request ist die Anfrage des Clients. Sie enthält mindestens die gewünschte Adresse und eine HTTP-Methode. Je nach API kommen weitere Informationen hinzu, beispielsweise Parameter, Daten, Header oder ein Zugangstoken.

Response

Die Response ist die Antwort des Servers. Sie kann angeforderte Daten, eine Bestätigung über eine ausgeführte Aktion oder eine Fehlermeldung enthalten.

Header

HTTP-Header übertragen zusätzliche Informationen zur Anfrage oder Antwort. Darüber können beispielsweise das gewünschte Datenformat, eine Authentifizierung oder technische Angaben übermittelt werden.

Body

Der sogenannte Body enthält die eigentlichen Nutzdaten einer Anfrage oder Antwort. Bei einer neuen Bestellung könnte ein Request-Body beispielsweise die Artikelnummer und Bestellmenge enthalten.

Bei einer einfachen GET-Anfrage ist nicht zwingend ein Request-Body erforderlich.

Welche HTTP-Methoden verwenden REST-APIs?

Viele moderne Web-APIs orientieren sich am REST-Prinzip. REST steht für „Representational State Transfer“ und beschreibt einen Architekturstil für Schnittstellen. REST ist kein eigenes Netzwerkprotokoll. RESTful Web-APIs verwenden normalerweise HTTP.

Dabei bestimmt die HTTP-Methode, was mit einer Ressource geschehen soll.

Methode	Typische Aufgabe
GET	Daten abrufen
POST	Neue Daten oder eine neue Ressource anlegen
PUT	Eine Ressource vollständig erstellen oder ersetzen
PATCH	Teile einer vorhandenen Ressource ändern
DELETE	Eine Ressource löschen

Ein GET-Request könnte beispielsweise eine Liste von Produkten abrufen. Mit POST könnte eine Anwendung ein neues Produkt anlegen.

Eine ausführliche Referenz zu den einzelnen HTTP-Methoden findest du in der HTTP-Dokumentation von MDN.

Welche Methoden tatsächlich unterstützt werden und was sie genau bewirken, entscheidet die jeweilige API. Deshalb ist die Dokumentation des Anbieters wichtiger als allgemeine Beispiele.

Einsteiger sollten vor allem zwischen GET und POST unterscheiden können. GET dient typischerweise zum Lesen von Daten. POST übermittelt Daten an den Server und kann dort eine Änderung auslösen.

Was bedeuten die Statuscodes einer API?

Zusammen mit der Antwort sendet eine HTTP-basierte API einen Statuscode. Dadurch kann der Client erkennen, ob die Anfrage erfolgreich war oder weshalb sie fehlgeschlagen ist.

Einige Codes begegnen dir bei APIs besonders häufig:

Statuscode	Bedeutung
200 OK	Anfrage wurde erfolgreich verarbeitet
201 Created	Eine neue Ressource wurde erfolgreich angelegt
204 No Content	Aktion erfolgreich, aber ohne Antwortinhalt
400 Bad Request	Anfrage ist fehlerhaft oder unvollständig
401 Unauthorized	Erforderliche Authentifizierung fehlt oder ist ungültig
403 Forbidden	Zugriff wurde verweigert
404 Not Found	Angeforderte Ressource wurde nicht gefunden
429 Too Many Requests	Zu viele Anfragen innerhalb eines bestimmten Zeitraums
500 Internal Server Error	Fehler auf der Serverseite
503 Service Unavailable	Dienst ist momentan nicht verfügbar

Gerade bei der Fehlersuche sind diese Codes hilfreich. Eine 404-Antwort deutet auf ein anderes Problem hin als ein Statuscode 401.

Eine gute Anwendung wertet deshalb nicht ausschließlich die zurückgegebenen Daten aus. Sie muss auch mit Fehlercodes, Zeitüberschreitungen und vorübergehend nicht erreichbaren Diensten umgehen können.

Welche Arten von APIs gibt es?

APIs können nach unterschiedlichen Kriterien eingeteilt werden. Deshalb führen Aufzählungen verschiedener „API-Arten“ schnell zu Missverständnissen.

Eine sinnvolle Unterscheidung ist zunächst die Frage, wer auf eine API zugreifen darf.

Öffentliche APIs

Eine öffentliche oder Public API richtet sich an externe Entwickler. Das bedeutet jedoch nicht automatisch, dass die Nutzung kostenlos oder ohne Anmeldung möglich ist.

Ein Anbieter kann eine Registrierung, einen API-Schlüssel oder einen kostenpflichtigen Tarif verlangen. Häufig gelten zusätzlich Begrenzungen für die Zahl der Abfragen.

Private APIs

Private APIs werden nur innerhalb eines Unternehmens oder eines abgeschlossenen Systems verwendet.

So können beispielsweise verschiedene interne Anwendungen über festgelegte Schnittstellen Daten austauschen, ohne ihre internen Programmstrukturen direkt voneinander abhängig zu machen.

Partner-APIs

Partner-APIs werden ausgewählten Geschäftspartnern zur Verfügung gestellt. Der Zugriff ist kontrollierter als bei einer öffentlichen Schnittstelle und setzt normalerweise eine entsprechende Berechtigung voraus.

Unabhängig von diesen Zugriffsarten gibt es verschiedene technische Ansätze für Web-APIs.

REST

RESTful APIs arbeiten typischerweise mit Ressourcen, HTTP-Methoden und Statuscodes. Als Datenformat wird häufig JSON verwendet.

REST ist bei Webdiensten weit verbreitet und für Einsteiger vergleichsweise leicht nachvollziehbar.

GraphQL

GraphQL verfolgt einen anderen Ansatz. Der Client gibt in seiner Abfrage an, welche Felder er tatsächlich benötigt.

Dadurch kann eine Anwendung gezielt bestimmte Daten und miteinander verbundene Informationen abfragen. GraphQL kennt unter anderem Queries zum Lesen von Daten und Mutations zum Verändern von Daten.

SOAP

SOAP ist ein standardisiertes Nachrichtenprotokoll für den Austausch strukturierter Informationen. SOAP-Nachrichten basieren auf einem festgelegten Nachrichtenformat und werden häufig mit XML verarbeitet.

SOAP begegnet dir vor allem bei älteren oder stark standardisierten Unternehmensanwendungen. Für einen ersten Einstieg in Web-APIs ist REST meist leichter zu verstehen.

REST, GraphQL und SOAP sind damit keine Alternativen zu „öffentlicher API“ oder „privater API“. Eine private Unternehmensschnittstelle kann beispielsweise als REST-API umgesetzt sein.

Wofür werden APIs im Alltag eingesetzt?

Viele alltägliche Softwarefunktionen wären ohne Schnittstellen deutlich aufwendiger umzusetzen.

Typische Einsatzgebiete sind beispielsweise:

• Abruf von Wetter-, Verkehrs- oder Geodaten
• Zahlungsabwicklung in Onlineshops
• Versand von E-Mails oder Nachrichten durch andere Anwendungen
• Synchronisierung zwischen verschiedenen Diensten
• Anbindung von Warenwirtschaft und Onlineshop
• Anmeldung über einen externen Benutzeraccount
• Steuerung von Smart-Home-Geräten im Internet der Dinge (IoT)
• Zugriff auf Cloud-Dienste
• Automatisierung wiederkehrender Arbeitsabläufe
• Austausch von Daten zwischen Apps und Webseiten

Auch WordPress verwendet zahlreiche Programmierschnittstellen. Plugins können beispielsweise Funktionen von WordPress nutzen, ohne den eigentlichen WordPress-Kern verändern zu müssen.

Bei Webdiensten kommt noch ein weiterer Vorteil hinzu: Der Anbieter kann seine interne Technik ändern, solange die vereinbarte API-Schnittstelle erhalten bleibt. Der Client muss dann nicht automatisch angepasst werden.

Wie nutzt man eine API?

Zum Ausprobieren einer Web-API brauchst du nicht sofort ein eigenes umfangreiches Programm. Viele Schnittstellen lassen sich zunächst über das Terminal oder spezielle API-Programme wie Postman oder Insomnia testen.

Der Ablauf ist fast immer ähnlich.

1. API-Dokumentation lesen

Die Dokumentation ist der wichtigste Ausgangspunkt. Dort findest du unter anderem:

• verfügbare Endpunkte
• unterstützte HTTP-Methoden
• benötigte Parameter
• Authentifizierung
• Datenformate
• mögliche Fehlercodes
• Nutzungslimits
• Beispielanfragen

Ohne Dokumentation müsstest du erraten, welche Anfragen ein Server versteht. Genau das soll eine sauber beschriebene API verhindern.

2. Passenden Endpoint auswählen

Danach suchst du den Endpunkt für die gewünschte Aktion.

Möchtest du beispielsweise Informationen zu einem bestimmten Objekt abrufen, benötigst du normalerweise einen GET-Endpunkt. Zum Anlegen neuer Daten wird häufig POST verwendet.

3. Authentifizierung einrichten

Nicht jede API benötigt eine Anmeldung. Bei vielen Diensten musst du jedoch nachweisen, wer die Anfrage stellt und welche Berechtigungen vorhanden sind.

Welche Methode verwendet wird, bestimmt der Anbieter.

4. Anfrage senden

Eine API lässt sich unter anderem mit curl aufrufen. Als ungefährliches Praxisbeispiel eignet sich ein öffentlich zugängliches Test-Repository bei GitHub.

Mit folgender Anfrage werden Informationen zu diesem Repository abgerufen:

curl.exe -L "https://api.github.com/repos/octocat/Hello-World" -H "Accept: application/vnd.github+json"

Die Antwort enthält zahlreiche Informationen im JSON-Format. Ein gekürzter Ausschnitt sieht beispielsweise so aus:

{
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "private": false,
  "description": "My first repository on GitHub!"
}

Damit hast du bereits eine echte API benutzt. curl schickt den GET-Request an den GitHub-Endpunkt und gibt die Antwort des Servers aus.

Bei anderen APIs kann der gleiche grundlegende Ablauf gelten, auch wenn Endpoint, Parameter und Authentifizierung anders aussehen.

5. Antwort auswerten

Ein Programm würde die JSON-Antwort anschließend verarbeiten.

Benötigt die Anwendung beispielsweise nur den Wert aus dem Feld name, kann sie diesen aus der Antwort auslesen und weiterverwenden. Wie das geschieht, hängt von der verwendeten Programmiersprache ab.

Braucht jede API einen API-Key?

Ein API-Key ist eine mögliche Form der Zugriffssteuerung, aber nicht jede API benötigt einen Schlüssel.

Bei öffentlichen Daten können einige Schnittstellen bestimmte Anfragen ohne Authentifizierung zulassen. Andere Anbieter verlangen bereits beim ersten Aufruf einen API-Key.

Ein API-Key wird häufig in einem HTTP-Header oder entsprechend den Vorgaben des Anbieters übertragen. Er dient unter anderem dazu, Anfragen einem Benutzer oder einem Projekt zuzuordnen.

API-Keys sollten wie Zugangsdaten behandelt werden. Sie gehören nicht offen in öffentlich einsehbaren Quellcode, ein GitHub-Repository oder eine Webseite, wenn der Anbieter den Schlüssel als geheim einstuft.

API-Key, Bearer-Token und OAuth: Wo liegt der Unterschied?

Bei APIs begegnen dir mehrere Verfahren zur Authentifizierung und Autorisierung.

API-Key

Der API-Key ist ein vom Anbieter ausgegebener Schlüssel. Er identifiziert häufig eine Anwendung oder ein Projekt und kann mit bestimmten Berechtigungen oder Nutzungslimits verbunden sein.

Das genaue Sicherheitsmodell hängt vom jeweiligen Dienst ab.

Bearer-Token

Ein Bearer-Token wird häufig über den HTTP-Header Authorization übertragen:

Authorization: Bearer DEIN-TOKEN

Wer ein gültiges Bearer-Token besitzt, kann die damit verbundenen Rechte nutzen. Solche Tokens müssen deshalb geschützt und ausschließlich über verschlüsselte HTTPS-Verbindungen übertragen werden.

OAuth 2.0

OAuth 2.0 kommt häufig zum Einsatz, wenn eine Anwendung im Auftrag eines Benutzers auf bestimmte Daten eines anderen Dienstes zugreifen soll.

Der Benutzer muss der fremden Anwendung sein Passwort dabei nicht geben. Stattdessen erhält die Anwendung nach der Freigabe ein Zugriffstoken mit den vorgesehenen Berechtigungen.

Welche Variante für dich relevant ist, ergibt sich aus der API-Dokumentation. Ein eigenes Authentifizierungsverfahren solltest du bei der Nutzung einer fremden API nicht konstruieren.

Was sind Rate-Limits?

API-Anbieter erlauben häufig nur eine bestimmte Zahl von Anfragen innerhalb eines Zeitfensters. Solche Begrenzungen werden als Rate-Limits bezeichnet.

Sie verhindern unter anderem, dass einzelne Anwendungen einen Dienst mit sehr vielen Anfragen überlasten. Gleichzeitig können Anbieter damit unterschiedliche Nutzungstarife oder Zugriffsrechte umsetzen.

Wird ein Limit überschritten, kann eine API beispielsweise den HTTP-Statuscode 429 Too Many Requests zurückgeben.

Eine Anwendung sollte Rate-Limits deshalb berücksichtigen. Bei häufig benötigten Daten kann es sinnvoll sein, Ergebnisse zwischenzuspeichern, unnötige Anfragen zu vermeiden und die Vorgaben des Anbieters für Wiederholungsversuche zu beachten.

Bei GitHub unterscheiden sich die Limits beispielsweise danach, ob eine Anfrage authentifiziert oder ohne Authentifizierung erfolgt. Solche Werte sind anbieterabhängig und können sich ändern. Die aktuellen Werte findest du deshalb am zuverlässigsten in der GitHub-Dokumentation zu den API-Limits.

Wie findest du eine passende API?

Die Zahl der verfügbaren Schnittstellen ist groß. Trotzdem sollte die Auswahl nicht allein davon abhängen, ob eine API die gewünschten Daten grundsätzlich bereitstellt.

Prüfe vor einer Integration mindestens diese Punkte:

• Ist die API offiziell dokumentiert?
• Werden die benötigten Daten und Funktionen angeboten?
• Welche Authentifizierung ist erforderlich?
• Welche Rate-Limits gelten?
• Ist die Nutzung kostenlos oder kostenpflichtig?
• Gibt es Einschränkungen für die Verwendung der Daten?
• Wie werden Änderungen und neue API-Versionen angekündigt?
• Welche Daten werden an den Anbieter übertragen?
• Gibt es eine Testumgebung?
• Wie verständlich sind Fehlerbeschreibungen und Beispiele?

Für ein dauerhaftes Projekt ist eine gute Dokumentation besonders wichtig. Eine API kann technisch leistungsfähig sein und trotzdem viel Arbeit verursachen, wenn Änderungen schlecht dokumentiert werden.

Bei Diensten mit personenbezogenen oder vertraulichen Daten solltest du zusätzlich prüfen, welche Daten übertragen und gespeichert werden. Eine funktionierende Schnittstelle sagt noch nichts darüber aus, ob ihre Verwendung zu deinem Datenschutz- und Sicherheitskonzept passt.

Häufige Fehler beim Arbeiten mit APIs

Viele Probleme entstehen nicht durch komplizierte Programmierung, sondern durch kleine Abweichungen von der Dokumentation.

Falscher Endpoint

Ein Buchstabendreher oder eine falsche Versionsangabe genügt, damit eine Anfrage fehlschlägt. Ein Statuscode 404 kann ein Hinweis darauf sein.

Falsche HTTP-Methode

Ein Endpoint kann GET erlauben, aber POST ablehnen. Der Client muss deshalb die für den jeweiligen Endpunkt dokumentierte Methode verwenden.

Fehlende oder falsche Authentifizierung

Ein abgelaufener Token, ein fehlender API-Key oder unzureichende Rechte können zu Statuscodes wie 401 oder 403 führen.

Falsches Datenformat

Erwartet die API JSON, muss die Anfrage entsprechend aufgebaut sein. Bei Requests mit einem Body kann auch der passende Content-Type-Header erforderlich sein.

Rate-Limit überschritten

Zu viele Abfragen innerhalb kurzer Zeit können vorübergehend blockiert werden. Wiederholt ein Programm fehlgeschlagene Requests sofort in einer Endlosschleife, verschlimmert es das Problem.

Fehlerantworten werden ignoriert

Eine API liefert nicht bei jeder Anfrage brauchbare Daten. Programme müssen deshalb Statuscodes prüfen und damit rechnen, dass ein Server zeitweise nicht erreichbar ist.

Zugangsdaten landen im Quellcode

Ein fest eingetragener geheimer API-Key kann versehentlich veröffentlicht werden. Zugangsdaten sollten deshalb entsprechend den Empfehlungen des verwendeten Entwicklungs- und Hosting-Systems sicher gespeichert werden.

API und SDK sind nicht dasselbe

API und SDK werden gelegentlich gleichgesetzt, bezeichnen aber unterschiedliche Dinge.

Eine API definiert die Schnittstelle, über die Software auf bestimmte Funktionen zugreifen kann.

Ein SDK, ausgeschrieben „Software Development Kit“, ist dagegen ein Paket mit Werkzeugen für Entwickler. Es kann Bibliotheken, Dokumentation, Beispielcode und weitere Hilfsmittel enthalten.

Ein Anbieter kann beispielsweise eine Web-API bereitstellen und zusätzlich SDKs für Python, JavaScript oder andere Programmiersprachen anbieten. Das SDK vereinfacht dann den Zugriff auf die API, ersetzt sie aber nicht zwangsläufig.

Fazit: APIs werden verständlich, sobald du den Ablauf kennst

Der Begriff API wirkt zunächst abstrakt. Beim praktischen Einsatz läuft der Vorgang jedoch meist auf ein überschaubares Prinzip hinaus: Ein Client schickt eine definierte Anfrage an einen Endpoint und erhält eine definierte Antwort zurück.

Für den Einstieg musst du noch keine komplette Anwendung programmieren. Eine einfache GET-Anfrage und die dazugehörige JSON-Antwort reichen aus, um das Grundprinzip zu verstehen.

Danach lohnt es sich, schrittweise HTTP-Methoden, Statuscodes und Authentifizierung kennenzulernen. Wer diese Grundlagen beherrscht und die Dokumentation eines Anbieters lesen kann, findet sich auch bei unbekannten Web-APIs wesentlich schneller zurecht.