Was ist eine REST-API?

Eine REST-API ist eine Web-Schnittstelle, die Daten als Ressourcen unter eigenen Adressen bereitstellt und über die Standardmethoden von HTTP — GET, POST, PUT, PATCH und DELETE — gelesen und verändert wird. REST (Representational State Transfer) ist dabei kein Protokoll, sondern ein Architekturstil mit wenigen, klaren Regeln.

Beschrieben hat den Stil Roy Fielding im Jahr 2000 in seiner Dissertation. Heute folgen ihm die meisten Web-APIs, von Zahlungsanbietern über CRM-Systeme bis zu Buchhaltungsprogrammen. Was eine API grundsätzlich ist, steht im eigenen Artikel; hier geht es um die Technik hinter REST.

Ressourcen und URLs

Im Zentrum von REST stehen Ressourcen: Kunden, Aufträge, Rechnungen, Artikel. Jede Ressource hat eine eindeutige Adresse:

• /kunden — die Liste aller Kunden
• /kunden/1042 — ein bestimmter Kunde
• /kunden/1042/rechnungen — die Rechnungen dieses Kunden

Die Adresse beschreibt, was gemeint ist, die HTTP-Methode, was damit geschehen soll. Gute REST-APIs verwenden deshalb Substantive in den Pfaden und keine Verben wie /getKunde oder /deleteRechnung.

Die HTTP-Methoden

Idempotent heißt: Wird dieselbe Anfrage mehrfach gesendet, ist das Ergebnis dasselbe wie nach einem Mal. Das ist wichtig bei Netzwerkfehlern. Ein wiederholtes GET oder PUT richtet keinen Schaden an; ein wiederholtes POST kann einen Auftrag doppelt anlegen. Viele APIs bieten dafür einen Idempotenz-Schlüssel im Header, an dem der Server Wiederholungen erkennt.

Statuscodes in REST-APIs

Jede Antwort trägt einen dreistelligen Statuscode. Für REST sind vor allem diese relevant — die vollständige Übersicht liefert der Artikel HTTP-Statuscodes:

• 200 OK — Anfrage erfolgreich, Daten im Inhalt.
• 201 Created — Ressource angelegt; die Adresse steht im Header Location.
• 204 No Content — erfolgreich, aber ohne Inhalt, etwa nach einem Löschen.
• 400 Bad Request und 422 Unprocessable Content (früher „Unprocessable Entity“) — die Anfrage ist fehlerhaft oder die Daten verletzen Regeln.
• 401 Unauthorized und 403 Forbidden — nicht angemeldet bzw. keine Berechtigung.
• 404 Not Found — die Ressource gibt es nicht.
• 409 Conflict — Widerspruch zum aktuellen Zustand, etwa bei gleichzeitiger Bearbeitung.
• 429 Too Many Requests — Limit überschritten, später erneut versuchen.
• 5xx — Fehler auf Serverseite.

Eine saubere API liefert bei Fehlern zusätzlich eine lesbare Fehlermeldung im Inhalt. Eine API, die bei jedem Fehler „200 OK“ mit dem Wort „error“ im Text zurückgibt, erschwert jede Automatisierung.

JSON und Zustandslosigkeit

Das übliche Datenformat ist JSON: lesbar für Menschen, leicht zu verarbeiten für Programme. Ein Kunde sieht dann etwa so aus: {"id": 1042, "name": "Muster GmbH", "ort": "München"}.

Ein Grundprinzip von REST ist die Zustandslosigkeit: Jede Anfrage enthält alles, was der Server zur Bearbeitung braucht, einschließlich der Anmeldung, meist als Token im Header Authorization. Der Server merkt sich zwischen zwei Anfragen nichts über den Client. Das macht REST-APIs gut skalierbar, weil jede Anfrage von jedem Server beantwortet werden kann.

Weitere Bausteine einer durchdachten REST-API sind Paginierung (große Listen seitenweise abrufen), Filter über Query-Parameter wie ?status=offen und eine maschinenlesbare Beschreibung nach dem OpenAPI-Standard, aus der sich Dokumentation und Testwerkzeuge erzeugen lassen.

Versionierung

APIs ändern sich, angebundene Systeme sollen trotzdem weiterlaufen. Deshalb werden REST-APIs versioniert, meist im Pfad (/v1/kunden, /v2/kunden) oder über einen Header. Neue Felder dürfen hinzukommen, ohne dass die Version wechselt; wer Felder entfernt oder umbenennt, braucht eine neue Version und eine Übergangsfrist. Für Sie als Nutzer heißt das: Ankündigungen des Anbieters zu abgekündigten Versionen gehören in den Kalender.

Typische Fehler bei der Anbindung

• Limits ignoriert. Der erste vollständige Abgleich schickt tausende Anfragen auf einmal und wird mit 429 abgewiesen. Besser: Anfragen drosseln und bei 429 mit wachsender Wartezeit wiederholen.
• Nur die erste Seite gelesen. Wer die Paginierung übersieht, verarbeitet die ersten fünfzig Datensätze und hält das für den ganzen Bestand.
• Fehler nicht ausgewertet. Ein 4xx wird protokolliert, aber niemand schaut hin. Fehlerhafte Datensätze gehören in eine Liste mit Zuständigkeit.
• Zeitzonen und Formate. Datumswerte ohne Zeitzone, Beträge als Text mit Komma, Umlaute in falscher Kodierung — kleine Details, die bei der Buchhaltung große Folgen haben.
• Tokens laufen ab. Zugangstoken haben oft eine begrenzte Laufzeit. Die Verbindung muss sie selbstständig erneuern, sonst steht sie eines Morgens still.

REST vs. GraphQL

GraphQL lohnt sich vor allem, wenn eine Oberfläche viele verknüpfte Daten in einer Anfrage braucht, etwa eine App. Für die Anbindung von Geschäftssystemen bleibt REST der Standard.

In der Praxis: So hilft SEODACH

Wir binden bestehende REST-APIs an Ihre Systeme an und entwickeln eigene Schnittstellen, wo keine vorhanden sind — mit Dokumentation, Versionierung und Überwachung, damit die Verbindung auch nach dem nächsten Update des Anbieters läuft. Wo Änderungen sofort ankommen müssen, ergänzen wir die Abfragen um Webhooks. Mehr dazu unter Systemintegration. Brauchen Sie eine eigene Anwendung mit API für Kunden oder Partner, finden Sie das unter Web-Anwendungen.

Häufige Fragen

Was ist der Unterschied zwischen API und REST-API?

API ist der Oberbegriff für jede Programmierschnittstelle. Eine REST-API ist eine bestimmte Art davon: eine Web-Schnittstelle, die den Regeln des REST-Stils folgt.

Was bedeutet „RESTful“?

Eine API gilt als RESTful, wenn sie die REST-Prinzipien konsequent einhält: Ressourcen mit eigenen Adressen, passende HTTP-Methoden, Zustandslosigkeit und aussagekräftige Statuscodes.

Ist REST veraltet?

Nein. GraphQL und andere Ansätze haben ihre Einsatzgebiete, doch für die Verbindung von Geschäftssystemen ist REST weiterhin der verbreitetste Standard.