SkillForge | ATLAS

REST API

12 min read

REST API

Einführung

Du benutzt eine App, um dein Lieblingsessen zu bestellen. In wenigen Sekunden siehst du auf dem Smartphone, dass deine Bestellung im Restaurant angekommen ist. Oder du öffnest eine Wetter-App und bekommst sofort die aktuellen Daten für deine Stadt.

Chaos ohne API vs. Struktur mit REST API
Ohne API: Chaotische direkte Kommunikation. Mit REST API: Klare Struktur durch den Vermittler. — Bildrechte: Ausbildung-in-der-IT.de (KI-unterstützt)

In beiden Fällen laufen im Hintergrund unzählige Anfragen zwischen Programmen ab. Diese Programme „reden” jedoch nicht direkt miteinander, sondern nutzen APIs – Schnittstellen, die festlegen, wie Informationen ausgetauscht werden.

Eine besonders verbreitete Form dieser Schnittstellen sind REST-APIs, die mit einfachen Regeln und klarer Struktur funktionieren. Sie sorgen dafür, dass Apps, Webdienste und Server zuverlässig und nachvollziehbar miteinander kommunizieren können.

In dieser Lerneinheit lernst du, wie REST-APIs aufgebaut sind, welche Prinzipien dahinterstehen und wie du selbst kleine Schnittstellen entwerfen und absichern kannst. Von den Grundlagen über HTTP-Methoden bis hin zu Design, Sicherheit und Tests bekommst du das Handwerkszeug, um APIs zu verstehen und praktisch einzusetzen.

Lernziele

Nach dieser Lerneinheit kannst du:

  1. Grundlagen verstehen: Du kannst erklären, was eine API ist, die Prinzipien von REST benennen und den Zusammenhang zwischen REST und HTTP nachvollziehen.

  2. HTTP korrekt anwenden: Du setzt die wichtigsten HTTP-Methoden (GET, POST, PUT, PATCH, DELETE) und Statuscodes (z. B. 200, 201, 404, 422) im Kontext von REST-APIs richtig ein.

  3. API-Design und Sicherheit umsetzen: Du modellierst Ressourcen konsistent, gestaltest nachvollziehbare URIs, behandelst Fehler einheitlich und wendest grundlegende Sicherheitsmaßnahmen (HTTPS, Authentifizierung, Autorisierung, Eingangsvalidierung) an.

  4. Dokumentation und Qualitätssicherung nutzen: Du beschreibst eine API mit OpenAPI, kannst daraus Dokumentation und Clients ableiten und führst einfache Tests (Smoke-, Validierungs- und Negativtests) zur Sicherung der API-Qualität durch.

Überleitung

APIs gehören zu der Grundlage moderner Softwareentwicklung. Sie ermöglichen es, dass verschiedene Programme miteinander kommunizieren und Daten austauschen können.

Schauen wir uns an, was eine API ist, wie der Architekturstil REST funktioniert und wie HTTP als Protokoll dabei eingesetzt wird.

Was ist eine API?

Eine API (Application Programming Interface) ist eine Schnittstelle, die festlegt, wie Software-Komponenten Informationen austauschen. Sie beschreibt, welche Daten angefordert werden können, wie Antworten aussehen und wie Fehler kommuniziert werden. Ohne APIs könnten Programme nicht effizient miteinander sprechen.

Ein einfaches Beispiel ist eine Wetter-API: Ein Client stellt eine Anfrage wie

GET /weather?city=Berlin

und erhält eine strukturierte Antwort, etwa im JSON-Format. So kann eine App das Wetter anzeigen, ohne selbst alle Datenquellen verwalten zu müssen.

Warum REST?

APIs können unterschiedlich gestaltet sein. REST (Representational State Transfer) ist ein Architekturstil, der beschreibt, wie APIs im Web aufgebaut sein sollten. REST-APIs sind heute besonders verbreitet, weil sie leicht zu verstehen, skalierbar und standardisiert sind.

Die Prinzipien von REST – sogenannte Constraints – sind feste Vorgaben, die die Gestaltung einer REST-API bestimmen. Sie bewirken mehrere Dinge:

  • Klare Trennung: Client und Server sind unabhängig. Der Client ist für Darstellung und Interaktion zuständig, der Server für Daten und Geschäftslogik.
  • Zustandslosigkeit: Jede Anfrage enthält alle benötigten Informationen. Der Server merkt sich nichts von vorherigen Anfragen, was die Skalierbarkeit erleichtert.
  • Cacheability: Antworten können im Client oder auf Zwischenstationen gespeichert werden, sodass wiederholte Anfragen schneller beantwortet werden.
  • Einheitliche Schnittstelle: Alle Ressourcen werden über ein konsistentes Muster (HTTP-Methoden, Statuscodes) angesprochen. Das erleichtert das Verständnis und die Wiederverwendbarkeit.
  • Optionale Erweiterung: Mit Code on Demand kann der Server sogar zusätzlichen Code an den Client liefern.

Zusammen sorgen diese Eigenschaften dafür, dass REST-APIs robust, verständlich und kompatibel sind. Deshalb sind sie für viele Anwendungsszenarien im Web – etwa mobile Apps, öffentliche Schnittstellen oder den Datenaustausch zwischen Diensten – eine sinnvolle Wahl.

HTTP als Fundament

REST wird in der Praxis meist über das Protokoll HTTP umgesetzt. HTTP definiert Methoden (wie GET oder POST), Statuscodes und Header, die für eine standardisierte Kommunikation sorgen.

Ein Beispiel: Mit

GET /orders/123

fordert ein Client eine Ressource (eine Bestellung) an. Der Server antwortet mit dem Statuscode 200 OK und liefert die Daten im gewünschten Format zurück.

Methoden und Statuscodes

Methoden im Überblick

MethodeZweck
GETDaten abrufen, ohne Änderungen
POSTNeue Daten erstellen oder Aktionen auslösen
PUTDaten vollständig ersetzen
PATCHDaten teilweise aktualisieren
DELETEDaten löschen

Typische Statuscodes

StatuscodeBedeutung
200 OKAnfrage erfolgreich
201 CreatedRessource erfolgreich erstellt
404 Not FoundRessource nicht vorhanden
500 Internal Server ErrorFehler auf Serverseite

Ressourcen und ihre Adressen

Der zentrale Gedanke von REST sind Ressourcen: Objekte wie Bestellungen oder Kunden, die über eindeutige Adressen (URIs) erreichbar sind. Diese Adressen sollten klar und nachvollziehbar gestaltet werden. Eine Sammlung von Bestellungen könnte zum Beispiel unter /orders erreichbar sein. Eine einzelne Bestellung unter /orders/123. Filter und Sortierungen lassen sich über Query-Parameter ausdrücken, etwa /orders?status=open&sort=-createdAt.

Repräsentationen und Formate

Ressourcen können in unterschiedlichen Formaten dargestellt werden, am häufigsten in JSON. Damit Client und Server sich verständigen, wird über Header festgelegt, welches Format gewünscht ist (Accept) und welches Format die Antwort hat (Content-Type).

Ein Client könnte so fragen:

GET /orders/123
Accept: application/json

Die Antwort des Servers könnte lauten:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "status": "open"
}
⏳ Lädt Dataview-Inhalt...

Vom Konzept zum Design

Eine gute API beginnt mit einem klaren Ressourcenmodell. Überlege dir zuerst, welche Objekte (Ressourcen) in deinem System wichtig sind und wie sie zueinander in Beziehung stehen. Danach bestimmst du die passenden Endpunkte (URIs) und wählst konsistente Namen.

Beispiel Orders-API:

  • Ressource „Bestellung“ → /orders
  • Ressource „Kunde“ → /customers
  • Beziehung: Ein Kunde kann mehrere Bestellungen haben → /customers/{id}/orders

Wichtig ist, dass URIs selbsterklärend sind und konsistent bleiben.

Einheitliche Fehlerbehandlung

Fehler sind unvermeidlich und müssen verständlich zurückgemeldet werden. REST-APIs nutzen dazu oft das standardisierte Format Problem Details. Damit lassen sich Fehler maschinenlesbar und einheitlich darstellen.

Ein Beispiel für einen Validierungsfehler ist:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Invalid input",
  "status": 422,
  "detail": "Postal code is invalid",
  "instance": "/orders/123"
}

Erklärung:

  • 422 Unprocessable Entity signalisiert, dass die Anfrage verstanden wurde, aber fehlerhafte Daten enthält.
  • application/problem+json kennzeichnet das standardisierte Format.
  • type verweist auf eine Dokumentation des Fehlertyps.
  • title gibt eine kurze, lesbare Fehlerbeschreibung.
  • status enthält den HTTP-Statuscode.
  • detail beschreibt den Fehler genauer.
  • instance zeigt, auf welche Ressource sich der Fehler bezieht.

Sicherheit als Grundlage

APIs sind ein zentrales Angriffsziel. Deshalb gehören grundlegende Sicherheitsmaßnahmen immer dazu.

  • Transport: Alle Requests und Responses müssen über HTTPS erfolgen.
  • Authentifizierung: Typischerweise per Token (z. B. Bearer Token nach OAuth 2.0).
  • Autorisierung: Stelle sicher, dass ein Nutzer nur auf seine eigenen Daten zugreifen darf.
  • Eingangskontrolle: Validiere alle Eingaben streng, um Angriffe wie SQL-Injection oder Manipulationen zu verhindern.
  • Rate Limiting: Begrenze, wie viele Anfragen pro Zeit erlaubt sind, um Missbrauch zu verhindern.

Sicherheit wird nicht nachträglich „hinzugefügt“, sondern ist ein fester Bestandteil des Designs.

Dokumentation mit OpenAPI

Damit eine API verständlich und nutzbar ist, muss sie dokumentiert werden. OpenAPI ist ein Standard, mit dem APIs beschrieben werden können. Die Beschreibung enthält:

  • verfügbare Endpunkte,
  • erlaubte Methoden und Statuscodes,
  • Datenstrukturen und Formate,
  • Sicherheitsmechanismen.

Aus dieser Spezifikation können automatisch Dokumentationen (z. B. Swagger UI) und sogar Test-Clients erzeugt werden.

Beispiel (Auszug Orders-API in OpenAPI-Notation):

paths:
  /orders:
    get:
      summary: List all orders
      responses:
        '200':
          description: A list of orders
    post:
      summary: Create a new order
      responses:
        '201':
          description: Order created

Qualitätssicherung

Eine API muss nicht nur entworfen, sondern auch getestet werden. Bereits einfache Tests sichern die Qualität erheblich.

  • Smoke-Tests: Funktioniert der Endpunkt grundsätzlich? (GET /orders → 200 OK)
  • Validierungstests: Werden Eingaben korrekt geprüft? (POST /orders ohne Pflichtfeld → 422)
  • Negativtests: Liefert die API erwartete Fehlercodes bei falschen Anfragen?
  • Automatisierte Tests: Tools wie Postman oder REST Assured können Abläufe automatisiert prüfen.

Regelmäßige Tests verhindern, dass Änderungen bestehende Funktionen unbemerkt beschädigen.

⏳ Lädt Dataview-Inhalt...

Zusammenfassung

Zusammenfassung:

Grundlagen von REST-APIs

In Teil 1 hast du die wesentlichen Grundlagen für das Verständnis von REST-APIs kennengelernt. Der Schwerpunkt lag darauf, Begriffe klar zu definieren und erste praktische Zusammenhänge herzustellen.

  • Eine API ist eine Schnittstelle, über die Software-Komponenten miteinander kommunizieren. Sie beschreibt, welche Anfragen möglich sind und welche Antworten erfolgen.
  • REST ist ein Architekturstil mit festen Prinzipien (Constraints). Diese sorgen für Trennung von Client und Server, Zustandslosigkeit, Cachebarkeit und eine einheitliche Schnittstelle.
  • HTTP dient als technisches Fundament. Du kennst die wichtigsten Methoden (GET, POST, PUT, PATCH, DELETE) und kannst sie ihren Eigenschaften (sicher, idempotent) zuordnen.
  • Statuscodes vermitteln den Erfolg oder Misserfolg einer Anfrage (z. B. 200 OK, 201 Created, 404 Not Found, 500 Internal Server Error).
  • Ressourcen werden über URIs angesprochen. Klare Konventionen helfen beim Aufbau konsistenter Endpunkte.
  • Repräsentationen wie JSON beschreiben den Zustand von Ressourcen. Content Negotiation geschieht über Header wie Accept und Content-Type.
  • Fehlerdarstellung erfolgt konsistent im Format Problem Details (application/problem+json).
  • Das Praxisbeispiel Orders-API zeigte, wie einfache Endpunkte (GET, POST) funktionieren und wie unterschiedliche Methoden genutzt werden.

Design, Sicherheit, Dokumentation und Qualität

In Teil 2 hast du gelernt, wie man aus den Grundlagen eine belastbare, sichere und verständliche API gestaltet. Der Schwerpunkt lag auf Gestaltung, Absicherung und Dokumentation.

  • Ressourcenmodellierung und URI-Design: Ressourcen wie orders und customers werden konsistent benannt und über nachvollziehbare URIs zugänglich gemacht.
  • Fehlerbehandlung: Neben Statuscodes ist das standardisierte Problem-Details-Format zentral für klare Fehlermeldungen.
  • Sicherheit: APIs müssen über HTTPS betrieben, Anfragen authentifiziert und autorisiert werden. Eingaben sind streng zu validieren und Rate Limits schützen vor Missbrauch.
  • Dokumentation mit OpenAPI: OpenAPI bietet eine maschinenlesbare Spezifikation. Sie erleichtert das Erstellen von Dokumentationen, Clients und Tests.
  • Qualitätssicherung: Smoke-Tests, Validierungstests und Negativtests sichern die Funktionsfähigkeit ab. Automatisierte Test-Tools wie Postman oder REST Assured unterstützen dabei.
  • Das erweiterte Orders-API-Beispiel verdeutlichte, wie Endpunkte entworfen, abgesichert und dokumentiert werden können.

Graphansicht

Backlinks