Was ist die Payload in einer API-Interaktion?

Wenn ein Client und ein Server über eine API kommunizieren, sendet der erste eine Anfrage an den zweiten, der die Anfrage verarbeitet und eine Payload zurückgibt, die das Ergebnis der Operation enthält, das sowohl die Erstellung eines neuen Benutzers als auch das Abrufen von Informationen aus einer Datenbank betreffen kann.

Die Payload oder „Payload“ der Interaktion ist jener Teil der Kommunikation, der die zu übertragenden Daten enthält, zum Beispiel den Benutzernamen und die E-Mail-Adresse, die einem neuen Konto zugeordnet werden sollen, oder die Zusammenfassung der durchgeführten Operation.

Payload: was es ist und was es enthält

Bei der Datenübertragung ist die Payload der Teil der Nachricht, der die zu übertragenden Daten enthält, buchstäblich die „Payload“ des Informationsaustauschs zwischen Client und Server.

Wenn ein Client eine Anfrage sendet, überträgt er ein Datenpaket, das mehrere Anweisungen enthält, die notwendig sind, damit das Kommunikationsprotokoll funktioniert, wie Metadaten und Header, die Informationen wie den Inhaltstyp oder mögliche Fehlermeldungen transportieren. Die Payload befindet sich im selben Paket und enthält die tatsächlichen zu übertragenden Daten.

In einer Anfrage kann die Payload beispielsweise die Daten eines Benutzers enthalten, der sich anmeldet, oder die Abfrage in einem API-Aufruf, während sie in einer Antwort das Ergebnis der Operation oder die angeforderten Daten enthalten kann.

Der Inhalt der Payload hängt im Wesentlichen vom Kontext ab: Bei der Zahlungsabwicklung kann sie Anmeldedaten, Zahlungsdetails und Metadaten zur Transaktion enthalten; in sozialen Netzwerken kann sie Multimedia-Dateien übertragen; in Buchungssystemen kann sie Informationen wie Verfügbarkeit und Preise transportieren.

Die Payload in API-Aufrufen: einige Beispiele

Die Payload ist also die Nachricht, die tatsächlich zwischen Client und Server übertragen wird. Sie kann ein Bild, ein PDF oder eine Namensliste sein. In Interaktionen, die die Übertragung von Metadaten beinhalten, handelt es sich fast immer um ein Objekt im Json- oder XML-Format, dessen Inhalt je nach Art der Operation stark variieren kann.

Wenn wir zum Beispiel einen neuen Benutzer erstellen, muss die Anforderungs-Payload die Daten enthalten, die zur Erstellung des neuen Kontos erforderlich sind (z.?B.: {"username": "neuerBenutzer", "email": "[email protected]", "firstName": "Mario", "lastName": "Rossi"}), während die Antwort Informationen wie die ID des neuen Benutzers, seine Daten und eine Nachricht wie „Konto erfolgreich erstellt“ enthalten wird (z.?B.: {"id": "123", "username": "neuerBenutzer", "email": "[email protected]", "message": "Konto erfolgreich erstellt"}).

Wenn wir Informationen aus einer Datenbank abrufen, entspricht die Anforderungs-Payload der spezifischen Abfrage (z.?B. {"query": {vatCode_or_taxCode_or_id}}), während die Antwort die angeforderten Daten enthält, in unserem Fall {"taxCode": "12485671007", "companyName": "OPENAPI SPA", "vatCode": "12485671007"}.

Die Payload in Rest-APIs: HTTP-Methoden

In Rest-API-Aufrufen hängt der Inhalt der Payload auch stark von der verwendeten HTTP-Methode ab, die die auszuführende Aktion auf der angeforderten Ressource definiert:

• GET: wird verwendet, um Daten von einem Server zu lesen, z.?B. um Daten aus einer Datenbank abzurufen. In GET-Anfragen enthält die Payload die angeforderten Daten (siehe Beispiel oben). Sie wird nur in der Antwort verwendet, da die für die Anfrage benötigten Daten in der Regel bereits in der Request-Zeichenfolge oder im Objekt enthalten sind;
• POST: wenn eine neue Ressource auf dem Server erstellt wird, z.?B. ein neues Produkt in einem E-Commerce hinzugefügt wird, muss die Anforderungs-Payload die zur Erstellung der neuen Ressource erforderlichen Daten enthalten und ist ein Json wie {"name": "Produktname", "price": 123, "description": "Produktbeschreibung.", "category": "Produktkategorie"}. Die Antwort enthält das Ergebnis der Anfrage, d.?h. den Erfolgsstatus und Details zur Erstellung der neuen Ressource, z.?B. die ID und das Erstellungsdatum;
• PUT: bei der Aktualisierung von Ressourcen muss die Payload eine vollständige Darstellung der zu aktualisierenden Ressource enthalten, einschließlich der neuen zu setzenden Werte. Bei der Aktualisierung von E-Commerce-Produkten enthält die PUT-Anforderungs-Payload beispielsweise Informationen wie {"id": "123", "name": "Neuer Produktname", "price": "Neuer Preis", "available": true}. Die AntwortPayload enthält in der Regel einen Erfolgsstatus und eine Nachricht wie „Produkt erfolgreich aktualisiert“;
• DELETE: eine DELETE-Anfrage benötigt keine Payload, kann jedoch Informationen wie die ID der zu löschenden Ressource oder andere Details enthalten. Die Antwort enthält fast immer nur den Erfolgsstatus und gegebenenfalls einige Details zur Operation;
• PATCH: in PATCH-Anfragen enthält die Payload nur die zu ändernden Daten. Wenn wir zum Beispiel das E-Mail-Feld des Benutzers mit ID 123 aktualisieren wollen, enthält die an den Endpoint gesendete Payload nur die neue E-Mail-Adresse, während die Antwort die geänderten Elemente oder die gesamte aktualisierte Ressource zusammen mit dem Erfolgsstatus zurückgeben kann.

Die Payload in Interaktionen mit der Openapi

Die in einer API-Interaktion übermittelten Payloaden, insbesondere AntwortPayloaden, enthalten weitaus mehr als nur die angeforderten Daten. Sie beinhalten wichtige Informationen für die Verwaltung der Interaktion durch den Client, wie Erfolgsstatus (z.?B. „success“: true) und etwaige Textnachrichten (z.?B. „message“: „ungültiges Passwort“).

Die Openapi-API-Payloaden verwenden den Json-Standard. In API-Anfragen enthalten sie die Informationen der Anfrage, z.?B. Absender, Empfänger und Inhalt einer SMS.

In den Openapi-API-Antworten enthalten die Payloaden 4 Felder:

• Data: die übertragenen Daten. In einer Anfrage zum Versand eines Einschreibebriefs per API enthält der Abschnitt „data“ alle notwendigen Informationen für den Versand, wie Absenderdaten, Name und Adresse des Empfängers, die zu sendende Nachricht und Druckoptionen. In der Antwort sind dieselben Daten enthalten, sowie die URL des Dokuments und Zahlungsdetails;
• Success: zeigt den Erfolgsstatus an, kann "success": true oder "success": false sein;
• Error: übermittelt mögliche Fehlermeldungen;
• Message: der Abschnitt der Payload, der Nachrichten für Endbenutzer enthält, oft bei Fehlern oder fehlenden Daten in der Anfrage, z.?B. "ungültige Abfrage" oder "geben Sie die Zahlungsart an".

Die Payload ist, wie wir gesehen haben, der grundlegende Vertrag zwischen Client und Server, das Element, das die Absicht (Request) und das Ergebnis (Response) der Interaktion definiert. Daher kann ihre Struktur die Effizienz und Skalierbarkeit einer API-Architektur stark beeinflussen. Eine strenge und konsistente Payloadstruktur ist daher unerlässlich, um Interoperabilität und einfache Integration sowie effiziente und leicht wartbare Prozesse sicherzustellen.