Anatomie einer API-Anfrage und Antwort

Eine API-Interaktion ist im Kern ein Frage-und-Antwort-Spiel: Die Anwendung stellt eine Anfrage (etwa "gib mir Bestellung 8821"), und die API schickt eine Antwort zurück, die angeforderten Daten oder eine Fehlermeldung. Pro Aufruf gibt es genau ein Hin und ein Zurück.

Im Web läuft dieser Austausch über HTTP, dasselbe Protokoll, mit dem auch Ihr Browser Webseiten lädt. Der Client (eine App oder ein Browser) sendet die Anfrage, der Server antwortet. Das Praktische daran: Anfrage und Antwort sind nach demselben Schema aufgebaut.

Beide Nachrichten haben denselben Grundaufbau: eine Startzeile, optionale Header (Metadaten), eine Leerzeile und optional einen Body (die Nutzdaten). Startzeile und Header zusammen heißen Kopf (head), der Teil danach ist der Body.

Aufbau einer Anfrage (Request)

• Startzeile (request-line) mit drei Teilen: Methode, Anfrageziel und HTTP-Version. Die Methode (z. B. GET zum Abrufen, POST zum Senden von Daten) beschreibt die Absicht. Das Anfrageziel ist üblicherweise der Pfad, oft mit angehängtem Query-String im Format schluessel=wert (z. B. /users?page=2). Die Version ist fast immer HTTP/1.1.
• Header: Metadaten als Name: Wert-Zeilen. Wichtig sind etwa Host (Zieldomain), Authorization (Zugangsnachweis, z. B. ein Token), Content-Type (Format des Bodys, z. B. application/json) und Content-Length (Länge des Bodys in Bytes).
• Body (optional): die eigentlichen Daten, z. B. die Felder eines Formulars oder ein JSON-Objekt. GET-Anfragen haben in der Regel keinen Body, POST-Anfragen schon.

Aufbau einer Antwort (Response)

• Statuszeile (status line) mit drei Teilen: HTTP-Version, Statuscode und optionaler Begründungstext (reason phrase). Der numerische Statuscode zeigt Erfolg oder Fehler an, häufig sind 200 (OK), 201 (erzeugt), 404 (nicht gefunden) oder 302 (Umleitung). Der Text danach (z. B. Created) ist rein informativ.
• Header: Metadaten zur Antwort, etwa Content-Type (Format des zurückgegebenen Inhalts, meist application/json), Location (URL einer neu erzeugten Ressource), Server, Date oder Cache-Control.
• Body (optional): die zurückgegebene Ressource, bei APIs meist JSON.

In HTTP/1.x sind diese Nachrichten textbasiert und gut lesbar. Ab HTTP/2 werden sie in binäre Frames verpackt und die Versionsangabe entfällt in der Nachricht, die Bedeutung der Bestandteile bleibt aber identisch. Headernamen sind unabhängig von Groß- und Kleinschreibung.

GET /users?page=2 HTTP/1.1
Host: api.example.com
Authorization: Bearer abc123token
Accept: application/json

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

{
  "page": 2,
  "users": [ { "id": 7, "name": "Anna" } ]
}

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 52

{ "firstName": "Example", "email": "a@example.com" }

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://api.example.com/users/123

{
  "message": "New user created",
  "user": { "id": 123 }
}

Quellen

• HTTP messages MDN Web Docs (Mozilla)
• Overview of HTTP MDN Web Docs (Mozilla)