Was ist ein Payload in einer API? JSON, XML, Beispiele

Was ist ein Payload in einer API?

Der Payload (Nutzdaten) einer API ist der Teil einer Anfrage oder Antwort, der die eigentlichen Daten im Body transportiert, im Gegensatz zu URL, Methode, Headern und Statuscode, die ihn beschreiben. Bei einem POST, der einen Nutzer anlegt, ist das JSON dieses Nutzers der Payload; bei einer GET-Antwort ist es die angeforderte Ressource. Genau diesen Teil liest, prüft und speichert Ihr Anwendungscode.

Der Begriff stammt aus der Netzwerktechnik und meinte die Fracht eines Pakets im Gegensatz zu den Routing-Headern. Header sagen dem Server, wie er die Nachricht lesen soll; der Payload ist die Nachricht.

Wo der Payload in einer HTTP-Nachricht steht

Eine HTTP-Nachricht besteht aus Startzeile, Headern, einer Leerzeile und dem Body. Im Body steht der Payload.

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 73
Authorization: Bearer xyz123

{
  "name": "Alice",
  "email": "alice@example.com",
  "role": "member"
}

Alles oberhalb der Leerzeile sind Metadaten. Das JSON-Objekt darunter ist der Payload. Welche Methoden einen Payload senden:

• POST, PUT und PATCH senden normalerweise einen Request-Payload, denn ihr Zweck ist es, Daten an den Server zu schicken.
• GET, HEAD und DELETE haben normalerweise keinen Request-Body. Parameter stehen stattdessen im Pfad oder im Query-String (der Beitrag How are Parameters Sent in an HTTP POST Request? zeigt den Unterschied, auf Englisch).
• Antworten enthalten meist ebenfalls einen Payload. Ausnahmen sind Antworten ohne Inhalt wie 204 und 304.

Häufige Payload-Formate

• JSON ist der Standard der meisten REST-APIs: gut lesbar und in jeder Sprache unterstützt. Siehe Was ist JSON?
• XML ist älter und umfangreicher, aber bei SOAP und Unternehmensschnittstellen weiter verbreitet.
• application/x-www-form-urlencoded senden einfache HTML-Formulare: name=Alice&role=member.
• multipart/form-data bündelt Formularfelder und Dateien in einer Anfrage. Siehe multipart/form-data.
• Binärdaten (application/octet-stream, image/png) übertragen rohe Bytes wie Downloads und Bilder.
• Protocol Buffers und MessagePack sind kompakte Binärformate für gRPC und performancekritische APIs. Sie sind kleiner als JSON, aber ohne Dekodierung nicht lesbar.

Der Header Content-Type gibt an, um welches Format es sich handelt. Fehlt er oder ist er falsch, liest der Empfänger den Body falsch ein.

Payload-Größe und Limits

• Server begrenzen Request-Bodys. nginx setzt client_max_body_size standardmäßig auf 1m und antwortet bei größeren Bodys mit 413. RFC 9110 nennt diesen Status inzwischen "Content Too Large".
• Große Payloads kosten Zeit und Speicher. Viele Server puffern den ganzen Body, bevor sie ihn verarbeiten. Bei vielen parallelen Anfragen steigen dadurch Speicherbedarf und Latenz.
• Textpayloads komprimieren. gzip oder brotli (ausgehandelt über Accept-Encoding und Content-Encoding) verkleinern JSON meist deutlich, wie stark, hängt aber von den Daten ab.
• Nicht alles auf einmal liefern. Große Listen seitenweise ausgeben. Siehe API-Pagination.

Jeden empfangenen Payload validieren

• Struktur gegen ein Schema prüfen (JSON Schema, Zod, Pydantic) und Abweichungen ablehnen.
• Eine Maximalgröße erzwingen, damit eine einzelne riesige Anfrage nicht den Speicher füllt.
• Typen und Wertebereiche prüfen und nur erwartete Felder zulassen. Sonst kann ein Client "role": "admin" einschleusen (Mass Assignment).
• Die Identität des Aufrufers aus der Authentifizierung nehmen, nie aus einer ID im Payload.

Häufige Fehler

• Fehlender oder falscher Content-Type. Zu JSON-Bodys gehört Content-Type: application/json.
• Zeichensatz-Konflikte. Durchgehend UTF-8 verwenden, sonst kommen Umlaute und Emojis verstümmelt an.
• JSON in einem JSON-String. Als String eingebettetes JSON wird einmal maskiert, nicht zweimal.
• Ganze Payloads loggen. Passwörter, Tokens und personenbezogene Daten landen sonst im Log-Speicher. Sensible Felder vorher entfernen.
• Body bei GET senden. HTTP definiert dafür keine Bedeutung, Server und Proxys können ihn ignorieren oder ablehnen.

Payloads im Lasttest und Monitoring

Ein Test, der {"k":"v"} sendet, misst kaum etwas. Parsing, Validierung und Datenbankschreibzugriffe wachsen mit Größe und Form des Payloads. Verwenden Sie deshalb Bodys wie im echten Betrieb und variieren Sie sie je virtuellem Nutzer (siehe Data-Driven Load Testing Scripts, auf Englisch). Testen Sie außerdem knapp unter und knapp über dem Größenlimit und erwarten Sie ein sauberes 413 statt eines 500. Prüfen Sie beim API-Testing den Response-Body, nicht nur den Statuscode.

LoadFocus führt Ihre JMeter- und k6-Skripte aus 25 Cloud-Regionen aus (Lasttests), und mit den Schritten in cURL, HAR, Postman oder OpenAPI in einen Lasttest umwandeln (auf Englisch) starten Sie aus einem cURL-Befehl. Für laufende Prüfungen kann API-Monitoring Statuscode, Response-Body, Header und Antwortzeit prüfen. Einen einzelnen Payload senden Sie im Browser mit dem kostenlosen Tool curl online; die Flags stehen unter curl-Befehl.

Häufige Fragen zu API-Payloads

Gehört die URL zum Payload?

Nein. Pfad und Query-String sind Metadaten, die die Ressource bezeichnen. Der Payload ist der Body.

Haben GET-Anfragen einen Payload?

In der Praxis nicht. HTTP definiert für einen GET-Body keine Bedeutung, viele Server und Proxys ignorieren ihn. Nutzen Sie bei GET Pfad- oder Query-Parameter.

Was ist der Unterschied zwischen Payload und Body?

Die Begriffe sind fast synonym. Body ist der HTTP-Begriff für die Bytes nach den Headern, Payload der gängige Begriff für die eigentlichen Daten darin.

Kann eine Antwort ohne Payload kommen?

Ja. Antworten mit 204 No Content und 304 Not Modified haben keinen Body, und ein DELETE liefert oft 204.

Wie groß darf ein Payload sein?

Das legen Server, Proxy oder Gateway vor Ihrer API fest, nicht HTTP selbst. nginx nutzt standardmäßig 1m. Prüfen Sie das Limit auf jeder Ebene und passen Sie es an Ihren Fall an.

Wie teste ich API-Payloads unter Last?

Nutzen Sie ein Tool, das Bodys je virtuellem Nutzer parametrisieren kann, etwa JMeter oder k6, und senden Sie realistische Größen und Formen statt minimaler Platzhalter.