REST API verstehen: Anfragen, Antworten und Tokens im IT-Alltag

Eine REST API ist eine Web-Schnittstelle, über die ein Programm bei einem anderen Programm Daten abfragt oder ändert, und zwar mit gewöhnlichen HTTP-Anfragen an feste Adressen. Ein Beispiel: Mit GET /v1.0/users liefert Microsoft Graph, die REST API von Microsoft 365, die Benutzerliste eines Mandanten.

Hinter vielen Abläufen im IT-Alltag steckt so eine Schnittstelle. Das Monitoring eröffnet ein Ticket, ein Skript legt neue Kolleginnen in Microsoft 365 an, oder der IT-Dienstleister gleicht Tickets mit seinem eigenen System ab. Wer die Grundregeln kennt, versteht Fehlermeldungen schneller, stellt Dienstleistern die richtigen Fragen und kann kleine Automatisierungen selbst prüfen. Was eine Programmierschnittstelle allgemein ist, erklärt der Glossarartikel API.

Kurz zusammengefasst

• Adresse und Methode: Die Methode sagt, was passieren soll (GET lesen, POST anlegen, PATCH ändern, DELETE löschen). Die Adresse sagt, womit.
• Antwort mit Nummer: Der Statuscode zeigt sofort, ob es geklappt hat (2xx) oder auf welcher Seite der Fehler liegt (4xx beim Aufrufer, 5xx beim Server).
• Ausweis bei jeder Anfrage: Der Server merkt sich nichts zwischen zwei Anfragen. Deshalb schickt jede Anfrage ihren Schlüssel oder ihr Token selbst mit.
• JSON als Format: Die Daten sind für Menschen lesbar und für Programme leicht zu verarbeiten.
• Grenzen der Schnittstelle: Lange Listen kommen seitenweise, und wer zu viele Anfragen schickt, wird mit Statuscode 429 gebremst.

Stand: November 2026 · Geprüft anhand von Microsoft Learn (Microsoft Graph), Roy T. Fieldings Dissertation, den IETF-Standards zu HTTP und OAuth 2.0 sowie der OWASP API Security Top 10 2023 (Quellen am Ende)

Eine Anfrage in fünf Teilen

Ob ein Skript Konten aus Microsoft 365 ausliest oder ein Überwachungstool eine Störung meldet: Jede REST-Anfrage setzt sich aus denselben Teilen zusammen. Das folgende Beispiel zeigt eine erfundene Ticket-Schnittstelle auf dem Platzhalter-Server itsm.example.com.

1. Methode:POST, weil ein neues Ticket entstehen soll.
2. Adresse (URI):/api/v1/tickets, also die Sammlung, in der das Ticket landet. Das v1 steht für die Version der Schnittstelle.
3. Header: Zusatzangaben, vor allem Authorization mit Token oder Schlüssel und Content-Type: application/json.
4. Body: die eigentlichen Daten, zum Beispiel { "titel": "Drucker 2. Stock offline", "standort": "Graz", "prioritaet": 3 }.
5. Antwort: Statuscode 201 Created und im Header Location die Adresse des neuen Tickets, etwa /api/v1/tickets/1288.

Die Feldnamen im Beispiel sind frei gewählt. Jede Schnittstelle legt ihre eigenen fest, meist in einer Beschreibung nach der OpenAPI-Spezifikation. Diese Beschreibung ist das Erste, was man vom Hersteller oder Dienstleister anfordern sollte.

Warum REST so funktioniert

Die Regeln gehen auf Roy T. Fielding zurück, der den Architekturstil im Jahr 2000 in seiner Dissertation beschrieben hat. Drei davon bemerkt man im Alltag direkt:

• Zustandslos: Der Server erinnert sich nicht an die vorige Anfrage. Darum muss jede Anfrage das Token mitschicken, und darum kann ein Load Balancer die Anfragen beliebig auf mehrere Server verteilen.
• Einheitliche Schnittstelle: Daten haben Adressen, die Aktion steckt in der Methode. Wer eine REST API kennt, findet sich in der nächsten schneller zurecht.
• Zwischenspeicher: Antworten auf GET dürfen gecacht werden, wenn der Server das per Header erlaubt.

Weitere Prinzipien sind die Trennung von Client und Server, mögliche Zwischenschichten wie Proxys sowie optional Code, den der Server mitliefert. Dazu kommt die Idee, dass Antworten Links zu den nächsten Schritten enthalten (Hypermedia). Viele Schnittstellen setzen diesen letzten Punkt nicht um, obwohl Fielding ihn für eine echte REST API voraussetzt.

Statuscodes: was die Antwort verrät

Bricht eine Integration ab, steht die Ursache meist schon im Statuscode. Die Tabelle zeigt die häufigsten Codes und den ersten sinnvollen Prüfschritt.

Für Wiederholungen nach einem Abbruch gilt: GET, PUT und DELETE darf ein Skript gefahrlos noch einmal senden, weil diese Methoden nach RFC 9110 idempotent sind. Ein wiederholtes POST kann dagegen ein zweites Ticket erzeugen. Manche Schnittstellen akzeptieren dafür einen Header Idempotency-Key, ob das unterstützt wird, steht in der Dokumentation.

Gute Schnittstellen erklären Fehler zusätzlich im Body, oft im Format Problem Details nach RFC 9457 mit Feldern wie title und detail. Diesen Text sollte man bei einer Supportanfrage immer mitschicken.

Und SOAP oder GraphQL?

Bei älteren Branchenlösungen trifft man noch auf SOAP-Schnittstellen mit XML, bei manchen Cloud-Diensten auf GraphQL, wo der Client die gewünschten Felder selbst zusammenstellt. Für den Alltag reicht meist die Frage, welche Schnittstelle der Hersteller anbietet und ob sie dokumentiert ist. Einen Überblick gibt der Glossarartikel API. Benachrichtigungen in die Gegenrichtung erklärt der Artikel Webhook.

Fünf Situationen aus dem IT-Alltag

1. Alle Benutzer aus Microsoft 365 auslesen

Microsoft Graph liefert bei GET /v1.0/users standardmäßig 100 Einträge pro Seite. Gibt es mehr, steht in der Antwort ein Link im Feld @odata.nextLink, den das Skript so lange aufruft, bis keiner mehr kommt. Wer nur die erste Seite liest, übersieht Konten, etwa bei einer Lizenzzählung. Für den Zugriff braucht das Skript eine App-Registrierung in Microsoft Entra ID mit passenden Berechtigungen. Mehr zum Verzeichnisdienst steht im Glossar Active Directory, zu unseren Leistungen rund um Microsoft 365 auf der Leistungsseite.

2. Das Skript läuft plötzlich nicht mehr

Kommt auf einmal 401, ist oft ein Token oder ein Client-Geheimnis abgelaufen. Geheimnisse von App-Registrierungen haben ein Ablaufdatum. Bewährt hat sich, dieses Datum als Ticket mit Fälligkeit oder als Kalendereintrag zu hinterlegen, damit der Tausch nicht erst nach dem Ausfall passiert.

3. Die Massenänderung wird gebremst

Bei vielen Anfragen in kurzer Zeit antwortet Microsoft Graph mit 429 und nennt im Header Retry-After eine Wartezeit. Das Skript wartet diese Zeit ab, statt sofort zu wiederholen. Sofortige Wiederholungen verlängern die Drosselung eher.

4. Der Dienstleister braucht Zugriff

Angenommen, ein Netzwerkdienstleister betreut die Firewalls an den Standorten Wien, Graz und Linz und möchte Störungen direkt als Ticket übermitteln. Vorab zu klären: ein eigener Zugang nur für diesen Zweck, nur die nötigen Rechte (Tickets anlegen und lesen, keine Benutzerverwaltung), eine Ansprechperson und ein Ablaufdatum. Endet der Vertrag, wird genau dieser Zugang gesperrt, ohne andere Integrationen zu stören.

5. Monitoring und Ticketsystem verbinden

Ein reales Beispiel ist die CCT Software Solutions GmbH in Wien, die Kundennetzwerke an über 90 Standorten überwacht. Laut Referenzbericht fragt eine REST-API-Schnittstelle die Events aus dem Monitoring laufend ab, und bei einem Problem entsteht automatisch ein Ticket in ky2help^®. Hat ein Provider ein eigenes Support-Tool, legt ky2help^® über die bidirektionale REST-API direkt ein Ticket in dessen System an und gleicht den Ticketstatus ab.

Für IT-Dienstleister

Checkliste für sichere Integrationen

Für kleine IT-Teams reichen wenige Regeln, wenn sie konsequent eingehalten werden:

• Nur HTTPS: keine Schnittstelle über unverschlüsseltes HTTP, auch nicht im internen Netz.
• Schlüssel sicher aufbewahren: API-Schlüssel und Client-Geheimnisse gehören in einen Passwort-Tresor, nie in die URL, in E-Mails oder in ein Skript auf dem Fileserver.
• Ein Zugang pro Integration: Jeder Dienstleister und jedes Skript bekommt einen eigenen Zugang. So lässt sich einer sperren, ohne die anderen zu treffen.
• OAuth 2.0 vorziehen: Ein API-Schlüssel ist ein statisches Passwort für eine Anwendung. OAuth 2.0 vergibt dagegen kurzlebige Tokens mit eingeschränkten Rechten. Microsoft Graph nutzt dieses Verfahren über Entra ID.
• Nur nötige Rechte: Ein Skript, das Benutzer liest, braucht kein Schreibrecht.
• Fremde Daten testen: Mit dem Zugang von Kunde A darf ein Aufruf mit der Ticketnummer von Kunde B nichts liefern. Diese Lücke steht in der OWASP API Security Top 10 2023 an erster Stelle.
• Stabile Versionen nutzen: Bei Microsoft Graph gehört in Skripte für den Betrieb v1.0, nicht beta. Microsoft unterstützt Beta-APIs in Produktionsanwendungen nicht.
• Protokolle führen: Welche Integration hat wann was geändert? Ohne diese Angabe wird jede Fehlersuche zur Detektivarbeit.

Wer dafür Unterstützung sucht, findet bei unseren Cybersecurity Services Prüfungen und Beratung. Ergänzend lohnt der Glossarartikel zur Multi-Faktor-Authentifizierung für die Administratorkonten, mit denen solche Zugänge verwaltet werden.

Fragen aus der Praxis

Was ist eine REST API in einfachen Worten?

Eine REST API ist ein fest vereinbarter Weg, über den zwei Programme per HTTP Daten austauschen. Das eine schickt eine Anfrage an eine Adresse, etwa „gib mir Ticket 1288“, und das andere antwortet mit einem Statuscode und den Daten, meist im JSON-Format.

Was ist der Unterschied zwischen Fehler 401 und 403?

401 heißt, dass der Server den Aufrufer nicht erkennt: Token oder Schlüssel fehlen, sind falsch oder abgelaufen. 403 heißt, dass der Aufrufer bekannt ist, aber keine Berechtigung für diese Aktion hat. Bei 401 hilft ein neues Token, bei 403 nur eine Änderung der Rechte.

Was tun bei Fehler 429 Too Many Requests?

Die Schnittstelle bremst, weil zu viele Anfragen in kurzer Zeit kamen. Das Skript sollte die im Header Retry-After genannte Zeit abwarten und danach mit größeren Abständen weitermachen. Sofortige Wiederholungen verlängern die Sperre meist.

Warum liefert die Schnittstelle nicht alle Datensätze auf einmal?

Große Ergebnislisten kommen seitenweise, damit Server und Netz nicht überlastet werden. Die Antwort enthält dann einen Verweis auf die nächste Seite, bei Microsoft Graph im Feld @odata.nextLink. Ein Skript ruft diese Verweise so lange ab, bis keiner mehr folgt.

Welche Berechtigungen braucht ein Skript für Microsoft Graph?

Das Skript braucht eine App-Registrierung in Microsoft Entra ID mit genau den Berechtigungen, die es benötigt. Liest es nur Benutzer, reichen Leserechte. Das Token holt es per OAuth 2.0. Das Client-Geheimnis hat ein Ablaufdatum, das man dokumentieren sollte.

Was bringt eine REST API in der Zusammenarbeit mit einem IT-Dienstleister?

Tickets müssen nicht doppelt erfasst werden. Beim Wiener Softwarehaus CCT legt ky2help® über die bidirektionale REST-API Tickets direkt im Support-Tool des Providers an, und der Ticketstatus wird über dieselbe Schnittstelle abgeglichen.

Quellen und Weiterlesen

Quellen

• Microsoft Learn: Paging von Microsoft Graph-Daten in Ihrer App
• Microsoft Learn: Microsoft Graph-Drosselungsleitfaden
• Microsoft Learn: Versionsverwaltung und Support für Microsoft Graph
• Roy T. Fielding: Representational State Transfer, Kapitel 5 der Dissertation
• IETF: RFC 9110 – HTTP Semantics und RFC 6585 – Statuscode 429
• IETF: RFC 9457 – Problem Details for HTTP APIs
• IETF: RFC 6749 – OAuth 2.0
• OWASP: API Security Top 10 2023 und REST Security Cheat Sheet

Weiterlesen

• API und Webhook
• Active Directory und Multi-Faktor-Authentifizierung
• Monitoring
• Referenz CCT Software Solutions
• ky2help® im IT-Bereich