Eine REST-API sicher anbinden und prüfen

Zwei Anwendungen verstehen sich noch nicht

Das Medienlabor Nordlicht verleiht Kameras und Mikrofone. Vor jeder neuen Ausleihe prüft ein externer Wartungsdienst die Geräte. Bisher überträgt eine Mitarbeiterin die Prüfanfragen von Hand aus der Ausleihsoftware in das Wartungsportal. Dabei werden Gerätenummern vertauscht und Rückmeldungen zu spät übernommen.

Die Ausleihsoftware soll deshalb eine Prüfanfrage über eine API an den Wartungsdienst senden. API steht für Application Programming Interface. Gemeint ist eine vereinbarte Schnittstelle, über die zwei Programme miteinander arbeiten können.

Dein Auftrag ist, einen Aufruf für eine neue Geräteprüfung zu entwerfen und die möglichen Antworten zu behandeln. Danach kannst du:

• eine passende Ressource und HTTP-Methode auswählen,
• die Teile einer HTTP-Anfrage und -Antwort erklären,
• JSON-Daten von der Schnittstelle selbst abgrenzen,
• Anmeldung, Berechtigung und Validierung unterscheiden,
• den vereinbarten Vertrag mit Erfolgs- und Fehlerfällen prüfen.

Du solltest JSON mit seinen Objekten, Arrays, Zeichenketten und Zahlen grundsätzlich lesen können. Die verwendete Programmiersprache ist für die Fachidee nicht entscheidend. Das Codebeispiel nutzt JavaScript, damit der gesamte Aufruf an einer Stelle sichtbar wird.

Eine API ist eine Vereinbarung zwischen Programmen

Die Ausleihsoftware ist der Client. Sie stellt eine Anfrage. Der Wartungsdienst ist der Server. Er verarbeitet die Anfrage und sendet eine Antwort. Die API legt fest, welche Anfragen erlaubt sind und wie beide Seiten Daten und Fehler beschreiben.

Bei einer REST-orientierten HTTP-API stehen Ressourcen im Mittelpunkt. Eine Ressource ist ein fachliches Objekt, etwa ein Gerät oder eine Geräteprüfung. Ein Endpunkt verbindet die Adresse einer Ressource mit einer erlaubten HTTP-Methode.

Für Nordlicht könnte eine neue Prüfung so angelegt werden:

POST /api/v1/geraete/G-204/pruefungen HTTP/1.1
Host: wartung.example.test
Authorization: Bearer <ZUGRIFFSTOKEN>
Content-Type: application/json
Accept: application/json

{
  "pruefart": "sicherheitspruefung",
  "faelligAm": "2026-08-14",
  "auftragReferenz": "NL-8042"
}

Die Adresse enthält das Gerät G-204. Der Pfad endet mit der Sammlung pruefungen, weil dort eine neue Prüfung entsteht. POST beschreibt das Anlegen innerhalb dieser Sammlung. Das Beispieltoken ist nur ein Platzhalter. Ein echtes Token gehört weder in eine öffentliche Lektion noch fest in den Quellcode.

Die Methode beschreibt die beabsichtigte Handlung

Die Methode ist kein beliebiges Verb. Sie trägt eine feste HTTP-Bedeutung. Für typische Ressourcenoperationen hilft diese Orientierung:

Diese Tabelle ist eine Entwurfshilfe, kein Automatismus. Ob eine API PUT oder PATCH anbietet und ob Löschen zulässig ist, steht in ihrem Vertrag. Ein Client darf keine Methode erfinden, nur weil sie fachlich passend wirkt.

Eine HTTP-Nachricht hat mehrere Aufgaben

Die erste Zeile der Anfrage nennt Methode, Ziel und HTTP-Version. Header transportieren Metadaten zur Nachricht. Der Body enthält hier die fachlichen Nutzdaten.

Im Beispiel übernehmen die Header unterschiedliche Aufgaben:

• Authorization übermittelt den Identitätsnachweis nach dem vereinbarten Verfahren.
• Content-Type: application/json sagt, in welchem Format der gesendete Body vorliegt.
• Accept: application/json beschreibt, welches Antwortformat der Client verarbeiten kann.

JSON ist dabei nur das Datenaustauschformat. Es beschreibt Objekte, Arrays und Werte. JSON legt nicht fest, an welche Adresse die Daten gehen, welche HTTP-Methode gilt oder welcher Statuscode zurückkommt. Diese Aufgaben gehören zur HTTP-API und ihrem fachlichen Vertrag.

Der Wartungsdienst könnte auf das erfolgreiche Anlegen so antworten:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/pruefungen/P-991

{
  "pruefungId": "P-991",
  "geraetId": "G-204",
  "status": "geplant",
  "faelligAm": "2026-08-14"
}

201 Created meldet, dass eine neue Ressource entstanden ist. Der Location-Header nennt ihre Adresse. Der JSON-Body liefert die für den Client wichtigen Daten. Ein anderer API-Vertrag könnte bei einem erfolgreichen Vorgang anders antworten. Deshalb müssen Client und Server dieselbe Dokumentation verwenden.

Statuscodes machen das Ergebnis maschinenlesbar

Ein Client sollte nicht nach Wörtern wie erfolgreich im Antworttext suchen müssen. Der dreistellige HTTP-Statuscode ordnet das Ergebnis zuerst grob ein.

401 und 403 werden häufig verwechselt. Bei 401 fehlt eine brauchbare Authentisierung. Bei 403 kennt der Server die Identität, verweigert aber die gewünschte Handlung. Ob ein Server aus Sicherheitsgründen stattdessen 404 verwendet, ist Teil des konkreten Schutz- und API-Konzepts.

Authentisierung, Autorisierung und Validierung lösen verschiedene Probleme

Die drei Prüfungen dürfen nicht ineinander verschwimmen:

1. Authentisierung: Wer stellt die Anfrage? Ein Zugriffstoken kann als Nachweis dienen.
2. Autorisierung: Darf diese Identität eine Prüfung für dieses Gerät anlegen?
3. Validierung: Sind die übermittelten Werte vollständig, formal gültig und fachlich erlaubt?

Ein gültiges Token macht ungültige Nutzdaten nicht richtig. Umgekehrt darf eine perfekt aufgebaute JSON-Nachricht ohne passende Berechtigung nicht verarbeitet werden.

Zugriffstoken sind Geheimnisse. Im produktiven Code kommen sie aus einer geschützten Laufzeitkonfiguration oder einem dafür vorgesehenen Secret-Speicher. Sie gehören nicht in Git, Protokollausgaben, Screenshots oder URLs. Die Übertragung erfolgt über HTTPS. Ein Token sollte außerdem nur die nötigen Rechte und eine begrenzte Gültigkeit erhalten.

Die API validiert alle Eingaben auf der Serverseite. Eine Prüfung im Browser verbessert zwar die Bedienung, schützt den Server aber nicht vor direkten oder veränderten Anfragen. Für das Szenario gehören mindestens diese Regeln in den Vertrag:

• pruefart ist einer der freigegebenen Werte,
• faelligAm ist ein vollständiges Datum im vereinbarten Format,
• auftragReferenz ist vorhanden und innerhalb der vereinbarten Länge,
• das Gerät existiert und darf durch das anfragende Konto bearbeitet werden,
• eine Wiederholung derselben Anfrage erzeugt nicht unbemerkt doppelte Aufträge.

Der Client behandelt Erfolg und Fehler bewusst

Dieses JavaScript-Beispiel zeigt die Verantwortung des Clients. Der Zugriffstoken wird übergeben, nicht im Programmtext fest eingetragen.

async function pruefungAnlegen({ basisUrl, token, geraetId, pruefung }) {
  const antwort = await fetch(
    `${basisUrl}/api/v1/geraete/${encodeURIComponent(geraetId)}/pruefungen`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
        Accept: "application/json"
      },
      body: JSON.stringify(pruefung)
    }
  )

  const istJson = antwort.headers
    .get("content-type")
    ?.includes("application/json")
  const daten = istJson ? await antwort.json() : null

  if (antwort.status === 201) {
    return { ok: true, pruefung: daten }
  }

  if (antwort.status === 401 || antwort.status === 403) {
    return { ok: false, grund: "zugriff", details: daten }
  }

  if (antwort.status === 409 || antwort.status === 422) {
    return { ok: false, grund: "fachlich", details: daten }
  }

  return { ok: false, grund: "unerwartet", status: antwort.status }
}

Der Code prüft zuerst, ob der Antwort-Header JSON ankündigt. Dadurch versucht er nicht, eine leere oder anders formatierte Antwort blind als JSON zu lesen. Danach unterscheidet er den erwarteten Erfolg, Zugriffsprobleme, fachliche Konflikte und unerwartete Ergebnisse.

Für einen produktiven Client fehlen noch Entscheidungen. Dazu gehören Zeitüberschreitungen, kontrollierte Wiederholungen und Protokollierung ohne Geheimnisse. Ein POST darf nicht unüberlegt wiederholt werden: Wenn die erste Antwort unterwegs verloren ging, könnte der Server den Auftrag bereits angelegt haben. Ein vereinbarter Idempotency-Key oder eine eindeutige Auftragsreferenz kann doppelte Aufträge verhindern. Das muss die API ausdrücklich unterstützen.

Ein Vertrag wird mit mehreren Fallarten geprüft

Ein erfolgreicher Beispielaufruf reicht nicht. Ein Vertragstest prüft, ob Client und Server die dokumentierte Vereinbarung an ihren Grenzen gleich verstehen.

Dabei werden nicht nur Statuscodes geprüft. Auch relevante Header, das Schema des Antwort-Bodys und die ausbleibende Zustandsänderung im Fehlerfall gehören zur Erwartung. Ein Fehler darf beispielsweise keinen halbfertigen Prüfauftrag hinterlassen.

Entwirf eine neue API-Anbindung

Damit steht die Anbindung

Eine belastbare API-Anbindung beginnt bei der fachlichen Ressource. Methode und Endpunkt beschreiben die Handlung, Header ordnen die Nachricht ein und JSON transportiert die Nutzdaten. Der Statuscode macht das Ergebnis zuerst maschinenlesbar.

Authentisierung, Autorisierung und Validierung beantworten drei getrennte Fragen: Wer fragt an, was darf diese Identität und sind die Daten gültig? Der Client behandelt jede Antwort bewusst und gibt weder Token noch interne Details unnötig weiter. Vertragstests prüfen schließlich nicht nur den Erfolgsweg, sondern auch Grenzen und abgewiesene Anfragen.

Die Lektion konzentriert sich auf eine synchrone, REST-orientierte HTTP-API. Ausführliche JSON-Modellierung, XML, SOAP, asynchrone Ereignisschnittstellen, OAuth-Abläufe, OpenAPI und verteilte Transaktionen gehören in eigene Lerneinheiten.

Belegmatrix