REST API: Architekturprinzipien, HTTP-Methoden und Einsatz in der Unternehmens-IT

Eine REST API ist eine Programmierschnittstelle, die dem Architekturstil Representational State Transfer (REST) folgt: Sie stellt Daten als Ressourcen unter eigenen URIs bereit, und Clients lesen oder ändern diese Ressourcen über die Standardmethoden von HTTP wie GET, POST, PUT, PATCH und DELETE.

Den Begriff hat Roy T. Fielding im Jahr 2000 in seiner Dissertation an der University of California, Irvine, geprägt. Fielding war an der Spezifikation von HTTP/1.1 beteiligt und beschrieb REST als Satz von Randbedingungen, nicht als Protokoll. Eine REST API ist deshalb weder ein Produkt noch eine Norm, sondern eine Bauweise.

In der Unternehmens-IT sind REST APIs der übliche Weg, Fachanwendungen, Cloud-Dienste und Werkzeuge wie Ticketsystem, Monitoring oder CMDB miteinander zu verbinden. Was eine Programmierschnittstelle grundsätzlich ist, erklärt der Glossarartikel API. Dieser Artikel geht in die Technik: Ressourcen, Methoden, Statuscodes, Authentifizierung und die Regeln, mit denen viele Schnittstellen einheitlich bleiben.

Das Wichtigste in Kürze

• Ressourcen statt Funktionsaufrufe: Jede Ressource hat einen URI, etwa /tickets/4711. Die Aktion steckt in der HTTP-Methode, nicht im Pfad.
• Zustandslos: Jede Anfrage enthält alles, was der Server zur Bearbeitung braucht, auch die Zugangsdaten.
• Idempotenz: GET, PUT und DELETE lassen sich wiederholen, ohne dass sich die Wirkung ändert. POST und PATCH sind ohne zusätzliche Vorkehrung nicht idempotent.
• Statuscodes und JSON: Der Statuscode zeigt, ob eine Anfrage erfolgreich war. Die Nutzdaten sind meist JSON nach RFC 8259.
• Sicherheit: API-Schlüssel identifizieren eine Anwendung, OAuth 2.0 vergibt kurzlebige Tokens mit begrenzten Rechten. Das größte Risiko laut OWASP ist eine fehlende Berechtigungsprüfung je Objekt.

Stand: November 2026 · Fachlich abgeglichen mit der Dissertation von Roy T. Fielding, den IETF-Standards RFC 9110, RFC 6749 und RFC 9457, der OWASP API Security Top 10 2023 und dem BSI IT-Grundschutz (Quellen am Ende des Artikels)

Die REST-Prinzipien nach Fielding

Fielding leitete REST aus den Eigenschaften ab, die das Web skalierbar gemacht haben. Kapitel 5 seiner Dissertation nennt sechs Randbedingungen (Constraints). Erst wenn eine Schnittstelle sie einhält, ist sie im strengen Sinn „RESTful“.

1. Client-Server: Oberfläche und Datenhaltung sind getrennt. Beide Seiten lassen sich unabhängig voneinander weiterentwickeln.
2. Zustandslosigkeit: Der Server speichert zwischen zwei Anfragen keinen Sitzungszustand des Clients. Weil jede Anfrage ihren Kontext selbst mitbringt, kann jeder Server im Verbund sie bearbeiten. Das vereinfacht Lastverteilung und Ausfallsicherheit.
3. Cache: Antworten geben an, ob und wie lange Zwischenspeicher sie aufbewahren dürfen. Dafür sind die HTTP-Header Cache-Control und ETag zuständig (RFC 9111).
4. Einheitliche Schnittstelle: Ressourcen sind über Bezeichner adressierbar und werden über Repräsentationen wie JSON bearbeitet. Nachrichten beschreiben sich selbst (Methode, Medientyp), und Hypermedia-Links zeigen die nächsten möglichen Schritte (HATEOAS).
5. Schichtenarchitektur: Zwischen Client und Server dürfen Proxys, API-Gateways oder Load Balancer liegen, ohne dass der Client davon wissen muss.
6. Code on Demand (optional): Der Server kann ausführbaren Code mitliefern. Für Schnittstellen zwischen Systemen spielt das kaum eine Rolle.

Ressourcen und URIs

Eine Ressource ist alles, was sich sinnvoll benennen lässt: ein Ticket, ein Benutzerkonto, eine Konfigurationseinheit oder die Liste aller offenen Incidents. Der URI identifiziert sie, die Repräsentation beschreibt ihren aktuellen Zustand. Bewährt haben sich Substantive im Plural für Sammlungen und IDs für einzelne Objekte:

• GET /tickets?status=offen liefert eine gefilterte Liste.
• GET /tickets/4711 liefert ein einzelnes Ticket.
• GET /tickets/4711/kommentare liefert eine untergeordnete Sammlung.

Pfade wie /createTicket oder /deleteUser widersprechen dem Prinzip, weil die Aktion schon in der Methode steckt. Solche Schnittstellen funktionieren, folgen aber eher dem Muster eines entfernten Funktionsaufrufs.

Nicht jede HTTP-API ist RESTful

Viele Schnittstellen, die sich REST API nennen, nutzen HTTP und JSON, verzichten aber auf Hypermedia-Links. Fielding hat 2008 klargestellt, dass eine API ohne Hypertext-Steuerung nach seiner Definition keine REST API ist. Im Sprachgebrauch hat sich der Begriff trotzdem für ressourcenorientierte HTTP-Schnittstellen durchgesetzt. Für Integrationsprojekte ist wichtiger, dass die Schnittstelle konsistent aufgebaut und vollständig dokumentiert ist.

HTTP-Methoden, Idempotenz und Statuscodes

RFC 9110 legt die Bedeutung der HTTP-Methoden fest. Für Integrationen zählen zwei Eigenschaften. Sicher ist eine Methode, wenn sie nur liest. Idempotent ist sie, wenn mehrere gleiche Anfragen dieselbe Wirkung haben wie eine einzige. Das wird wichtig, sobald eine Verbindung abbricht und der Client nicht weiß, ob seine Anfrage angekommen ist.

Wer POST-Anfragen gefahrlos wiederholen will, braucht eine eigene Vorkehrung. Verbreitet ist ein vom Client erzeugter Schlüssel im Header Idempotency-Key, den die IETF derzeit als Internet-Draft standardisiert. Der Server merkt sich den Schlüssel und liefert bei einer Wiederholung das ursprüngliche Ergebnis, statt ein zweites Ticket anzulegen.

Statuscodes richtig lesen

Die erste Ziffer des dreistelligen Codes bestimmt die Klasse: 2xx Erfolg, 3xx Umleitung, 4xx Fehler auf Seiten des Clients, 5xx Fehler auf Seiten des Servers. In REST APIs begegnen einem vor allem diese Codes:

• 200 OK, 201 Created, 204 No Content: Erfolg. Bei 201 verweist der Header Location auf die neu angelegte Ressource.
• 400 Bad Request: Die Anfrage ist formal fehlerhaft, etwa ungültiges JSON.
• 401 Unauthorized und 403 Forbidden: 401 bedeutet fehlende oder ungültige Zugangsdaten, 403 einen bekannten Aufrufer ohne Berechtigung.
• 404, 409, 412, 422: Ressource nicht gefunden, Konflikt mit dem aktuellen Zustand, nicht erfüllte Vorbedingung (etwa bei If-Match mit veraltetem ETag) und fachlich ungültiger Inhalt (Unprocessable Content).
• 429 Too Many Requests: Ratenlimit überschritten (RFC 6585), häufig mit einem Header Retry-After.
• 500 und 503: interner Fehler oder Dienst vorübergehend nicht verfügbar.

Abgrenzung zu SOAP und GraphQL

REST ist nicht der einzige Schnittstellenstil. SOAP ist ein vom W3C spezifiziertes XML-Nachrichtenformat mit festem Umschlag und formalen Verträgen (WSDL). Man findet es vor allem in älteren Unternehmens- und Behördenschnittstellen. Bei GraphQL fragt der Client meist über einen einzigen Endpunkt genau die Felder ab, die er braucht. Einen Überblick über Schnittstellenarten gibt der Glossarartikel API. Ereignisse, die ein System von sich aus meldet, behandelt der Artikel Webhook.

Beispiel: ein Ticket per REST API anlegen

Angenommen, ein Monitoring-System soll bei einem ausgefallenen Dienst automatisch ein Incident-Ticket im ITSM-Werkzeug eröffnen. Die folgende Anfrage ist ein generisches Beispiel. Pfade und Feldnamen sind frei gewählt und entsprechen keiner bestimmten Produktschnittstelle.

POST /api/v1/tickets HTTP/1.1
Host: itsm.example.com
Authorization: Bearer eyJhbGciOi…
Content-Type: application/json
Idempotency-Key: 9f1c2a7e-…

{ "titel": "Mailserver nicht erreichbar",
  "kategorie": "incident",
  "prioritaet": 2,
  "ci": "srv-mail-01" }

War die Anfrage erfolgreich, antwortet der Server mit dem Statuscode 201 und nennt die Adresse des neuen Tickets:

HTTP/1.1 201 Created
Location: /api/v1/tickets/4711
Content-Type: application/json

{ "id": 4711, "status": "neu" }

Fehlt ein Pflichtfeld, kommt 422 zurück, mit einer Fehlerbeschreibung im Format Problem Details nach RFC 9457 (Medientyp application/problem+json):

{ "type": "/probleme/pflichtfeld",
  "title": "Pflichtfeld fehlt",
  "status": 422,
  "detail": "kategorie ist erforderlich" }

REST-Konventionen für viele Schnittstellen

Sobald mehr als eine Handvoll Schnittstellen im Einsatz ist, lohnt ein verbindlicher Styleguide. Jede neue Integration folgt dann demselben Muster, und Entwicklungsteams, Dienstleister und Betrieb sprechen über dieselben Begriffe. Fünf Punkte gehören hinein:

1. Beschreibung: Jede Schnittstelle wird mit der OpenAPI-Spezifikation maschinenlesbar beschrieben. Daraus lassen sich Dokumentation, Tests und Client-Code erzeugen.
2. Versionierung: Ein festes Schema für inkompatible Änderungen, zum Beispiel die Hauptversion im Pfad (/v1/, /v2/). Alternativen sind Abfrageparameter, Header oder Medientyp. Microsoft beschreibt alle vier Varianten im Azure Architecture Center. Alte Versionen werden mit Vorlauf abgekündigt.
3. Paginierung: Große Listen kommen seitenweise, über limit und offset, über einen Cursor oder über Link-Header nach RFC 8288 mit rel="next". Eine Obergrenze für die Seitengröße schützt den Server.
4. Fehlerformat: Einheitlich Problem Details nach RFC 9457, damit Clients Fehler maschinell auswerten können.
5. Namens- und Datenregeln: einheitliche Schreibweise der Felder, Zeitangaben nach ISO 8601 mit Zeitzone, JSON in UTF-8.

Im IT Service Management gehört jede neue Integration außerdem in Change Management und CMDB: Welche Anwendung greift mit welchem technischen Konto auf welche Ressourcen zu, wer ist verantwortlich, und wann läuft das Geheimnis ab?

ky2help^® bietet im Standard eine REST-API (Webservices) sowie Schnittstellen zu Active Directory, Azure AD (heute Microsoft Entra ID), E-Mail, MS Teams, Jira und ServiceNow. Für Massenoperationen gibt es Import- und Exportfunktionen. Wie das in einem Integrationsprojekt aussieht, beschreibt die Referenz CCT Software Solutions. Die Abläufe, die auf ein angelegtes Ticket folgen, passen Sie im Prozessdesigner per Drag-and-Drop an.

Automatisierung ansehen

Authentifizierung, Sicherheit und Betrieb

Eine REST API ist ein direkter Zugang zu Unternehmensdaten. Die OWASP API Security Top 10 2023 führen als größtes Risiko die fehlende Berechtigungsprüfung auf Objektebene (Broken Object Level Authorization, API1). Ein Client ändert die ID im Pfad, etwa von /tickets/4711 auf /tickets/4712, und erhält Daten, die ihm nicht zustehen. Dagegen hilft nur eine serverseitige Prüfung bei jedem einzelnen Zugriff.

API-Schlüssel oder OAuth 2.0?

• API-Schlüssel: ein statisches Geheimnis, das eine aufrufende Anwendung identifiziert. Schnell eingerichtet, aber meist ohne Ablaufdatum und ohne Bezug zu einem Benutzer. Er gehört in einen Header, nie in die URL, weil URLs in Logdateien und Verläufen landen.
• OAuth 2.0 (RFC 6749): ein Rahmenwerk für Autorisierung. Ein Autorisierungsserver stellt kurzlebige Access Tokens mit begrenzten Rechten (Scopes) aus, die der Client als Bearer Token nach RFC 6750 mitsendet. Für Server-zu-Server-Integrationen ist der Client-Credentials-Grant üblich, für Anwendungen im Namen eines Benutzers der Authorization Code Grant mit PKCE. Die Security Best Current Practice RFC 9700 vom Januar 2025 verbietet den Resource Owner Password Credentials Grant.

OAuth 2.0 regelt Berechtigungen, nicht die Anmeldung selbst. Wer die Identität eines Benutzers braucht, setzt OpenID Connect darauf. Hintergründe stehen in den Glossarartikeln Authentifizierung und Multi-Faktor-Authentifizierung.

Regeln für den Betrieb

• Transport und Anmeldung: ausschließlich HTTPS. Der BSI-Baustein APP.3.1 verlangt, dass sich Clients authentisieren, bevor sie auf geschützte Ressourcen eines Webservice zugreifen (Anforderung APP.3.1.A1).
• Ratenlimits: Der Server begrenzt Anfragen und antwortet mit 429. Clients warten die in Retry-After genannte Zeit ab und wiederholen danach mit wachsenden Abständen.
• Minimale Rechte: ein technisches Konto je Integration, nur mit den nötigen Scopes. Geheimnisse liegen in einem Tresor statt im Quelltext und werden regelmäßig getauscht.
• Datensparsamkeit: Antworten enthalten nur die Felder, die der Client braucht. Die OWASP führt zu großzügige Antworten als API3:2023.
• Inventar: Jede veröffentlichte Version ist dokumentiert, nicht mehr genutzte Versionen werden abgeschaltet (OWASP API9:2023).
• Nachverfolgbarkeit: Eine Korrelations-ID je Anfrage macht einen Fehler über mehrere Systeme hinweg auffindbar.

Häufige Fragen zur REST API

Wofür steht REST?

REST steht für Representational State Transfer. Roy T. Fielding hat den Architekturstil im Jahr 2000 in seiner Dissertation beschrieben. Clients bearbeiten dabei Ressourcen über Repräsentationen wie JSON, und jede Anfrage ist in sich vollständig.

Was ist der Unterschied zwischen PUT, PATCH und POST?

POST legt eine neue Ressource in einer Sammlung an oder stößt eine Verarbeitung an. PUT ersetzt eine Ressource vollständig unter einem bekannten URI. PATCH ändert nur einzelne Felder. PUT ist idempotent, POST nicht, PATCH nur, wenn die Schnittstelle es so umsetzt.

Welche HTTP-Methoden sind idempotent?

Nach RFC 9110 sind PUT und DELETE sowie die sicheren Methoden GET, HEAD, OPTIONS und TRACE idempotent. Mehrere gleiche Anfragen haben also dieselbe Wirkung wie eine einzige. POST und PATCH lassen sich etwa über einen Idempotency-Key-Header absichern.

Ist jede HTTP-Schnittstelle mit JSON eine REST API?

Nicht im strengen Sinn. Fielding verlangt unter anderem Hypermedia-Links, über die der Client die nächsten Schritte findet. Viele Schnittstellen verzichten darauf und heißen trotzdem REST API. In der Praxis sind Ressourcenorientierung, korrekte Methoden und Statuscodes entscheidend.

Was unterscheidet API-Schlüssel und OAuth 2.0?

Ein API-Schlüssel ist ein statisches Geheimnis, das eine Anwendung identifiziert, meist ohne Ablaufdatum. Bei OAuth 2.0 stellt ein Autorisierungsserver kurzlebige Tokens mit begrenzten Rechten aus, die der Client als Bearer Token mitsendet. Beides gehört in einen Header, nie in die URL.

Welche Rolle spielt die REST API von ky2help® im Ticketprozess?

ky2help® bietet im Standard eine REST-API für Webservices. Im Referenzprojekt mit CCT Software Solutions übernimmt eine REST-API-Schnittstelle laufend Events aus dem Monitoring und erzeugt bei Problemen automatisch Tickets. Außerdem legt ky2help® darüber Tickets im System von Providern an und gleicht deren Status ab.

Quellen und weiterführende Artikel

Quellen

• Roy T. Fielding: Architectural Styles and the Design of Network-based Software Architectures, Kapitel 5 (2000)
• Roy T. Fielding: REST APIs must be hypertext-driven (2008)
• IETF: RFC 9110 – HTTP Semantics und RFC 5789 – PATCH
• IETF: RFC 9457 – Problem Details for HTTP APIs
• IETF: RFC 6749 – OAuth 2.0 und RFC 9700 – OAuth 2.0 Security Best Current Practice
• IETF: Internet-Draft „The Idempotency-Key HTTP Header Field“
• OpenAPI Initiative: OpenAPI Specification
• Microsoft Learn: Bewährte Methoden für das RESTful-Web-API-Design
• OWASP: API Security Top 10 2023
• BSI: IT-Grundschutz-Baustein APP.3.1 Webanwendungen und Webservices (Edition 2023)

Weiterlesen im Glossar und auf kyberna.de

• API und Webhook
• Authentifizierung und Multi-Faktor-Authentifizierung
• CMDB und Monitoring
• DevOps
• ITIL Incident Management
• Funktionsumfang von ky2help®