Dateien an eine API senden: Multipart oder Base64 und beschädigte Uploads vermeiden

Der Endpoint bestimmt, wie die Datei gesendet wird

Eine Datei an eine API zu senden bedeutet, ihren Inhalt in eine HTTP-Anfrage einzubinden, die der Server interpretieren kann. Es gibt kein universelles Format, das für alle Endpoints geeignet ist: Einer erwartet möglicherweise einen multipart/form-data-Upload, ein anderer ein JSON-Objekt mit codiertem Inhalt und ein weiterer einen anderen, im Vertrag beschriebenen Mechanismus. Weder die Dateiendung noch die Tatsache, dass eine Anfrage POST verwendet, reichen aus, um die zu sendende Struktur festzulegen. Zuerst müssen Sie den konkreten Vorgang identifizieren und sich an dessen Vorgaben halten.

Wenn Sie die Darstellung der Datei von der Geschäftslogik trennen, lassen sich Probleme leichter diagnostizieren. Die Darstellung legt fest, wie die Bytes und Felder übertragen werden; der Endpoint bestimmt, welche Felder erfordert werden, welche Typen er akzeptiert und welche Antwort er zurückgibt. Wird ein für einen anderen Vorgang gültiger Body gesendet, kann der Server ihn ablehnen oder unerwartet verarbeiten. Notieren Sie vor dem Schreiben des Codes Methode, Route, Authentifizierung, Content-Type, erforderliche Felder, dokumentierte Limits und Fehlermeldungen.

• Leiten Sie das akzeptierte Format weder aus dem Routennamen noch aus einer Integration eines anderen Anbieters ab.
• Nutzen Sie Anforderungsbeispiele als Orientierung, prüfen Sie aber, ob sie zur selben Version und zum selben Vorgang gehören.

Multipart/form-data und Base64 in JSON

Bei multipart/form-data wird der Body in getrennte Teile aufgeteilt. Jeder Teil hat eigene Header und eigenen Inhalt. So kann eine Anfrage die Datei mit zusätzlichen Feldern kombinieren, sofern der Endpoint diese unterstützt. Der Client erstellt die Trennung zwischen den Teilen. Wenn Sie eine HTTP-Bibliothek verwenden, ist es deshalb normalerweise sinnvoll, die Bibliothek den vollständigen Content-Type-Header einschließlich des passenden Boundary-Parameters erzeugen zu lassen. Den Header manuell festzulegen, ohne den zum Body passenden Boundary-Wert beizubehalten, ist ein häufiger Grund dafür, dass der Server die Anfrage nicht analysieren kann.

Bei Base64 werden die Bytes der Datei in Text umgewandelt und dieser Text wird in ein JSON-Dokument eingebettet, zum Beispiel in eine vom Vertrag definierte Eigenschaft. Diese Codierung kann die übertragene Größe gegenüber der Binärdatei erhöhen und erfordert zusätzliche Umwandlungen bei der Vorbereitung und Verarbeitung des Inhalts. Gehen Sie weder davon aus, wie die Eigenschaft heißt, noch ob ein Medien-Typ-Präfix erforderlich ist oder der Endpoint Base64 akzeptiert: Das sind Vorgaben des Schemas. Vergleichen Sie bei großen Uploads den Aufwand und die dokumentierten Limits, bevor Sie sich entscheiden.

• Multipart eignet sich, wenn der Vertrag Formularteile und einen Dateiteil beschreibt.
• Base64 kommt nur infrage, wenn der Endpoint diese Darstellung vorgibt; ein JSON-Body allein reicht dafür nicht aus.

OpenAPI prüfen, ohne etwas vorauszusetzen

Rufen Sie die verfügbare OpenAPI-Spezifikation auf und suchen Sie anhand von Route und Methode nach dem genauen Vorgang. Prüfen Sie den Content-Type, den der Request-Body akzeptiert, das zugehörige Schema und die erforderlichen Eigenschaften. Bei Multipart sollten Sie prüfen, wie die Datei deklariert ist und welche Namen die Teile haben; bei JSON suchen Sie nach der angegebenen Struktur und dem Datentyp der einzelnen Felder. Die OpenAPI-Dokumentation ist relevant, weil die Annahme von Multipart-Uploads im Vertrag spezifiziert sein sollte, statt aus dem Bauchgefühl abgeleitet zu werden.

Lesen Sie auch die dokumentierten Antworten, Authentifizierungsanforderungen sowie alle Limits und Einschränkungen des Vorgangs. Ein Beispiel beschreibt nicht unbedingt alle gültigen Fälle, und fehlende Informationen bedeuten nicht, dass beliebige Dateien gesendet werden dürfen. Fehlt das Schema, ist der Content-Type unklar oder widersprechen sich die Anweisungen, bitten Sie die zuständige Stelle für die API um Klärung, bevor Sie mit der Programmierung beginnen. Halten Sie die für die Implementierung und Tests verwendete Vertragsversion fest.

• Prüfen Sie Methode, Route, Content-Type, Body-Schema, Pflichtfelder und mögliche Antworten.
• Leiten Sie Limits, Berechtigungen, unterstützte Formate oder Speicherung nicht aus einer allgemeinen Produktbeschreibung ab.

Anfrage erstellen und häufige Fehler vermeiden

In einem konzeptionellen Multipart-Beispiel sendet der Client einen Teil mit dem im Vertrag angegebenen Feldnamen und dem binären Dateiinhalt. Weitere Teile dürfen nur ergänzt werden, wenn sie dokumentiert sind. In einem konzeptionellen JSON-Beispiel lesen Sie die Bytes ein, codieren sie mit Base64 und fügen sie in die im Schema genau festgelegte Eigenschaft ein. Diese Beispiele beschreiben Muster und keine mit einem konkreten Apification-Endpoint kompatible Anfrage. Die Apification-Integration umfasst REST API und OpenAPI, doch die hier verfügbaren Informationen legen nicht fest, welcher Vorgang Dateien akzeptiert oder welches Schema er verwendet.

Prüfen Sie vor dem Senden, ob sich die Datei korrekt öffnen lässt und das Programm nicht versehentlich einen falschen Pfad, eine leere Datei oder eine unvollständige Version einliest. Verwechseln Sie den Namen oder die Dateiendung nicht mit dem MIME-Type: Sie müssen nicht übereinstimmen, und der zu übertragende Wert hängt vom Vertrag ab. Vermeiden Sie es, Base64 beim Protokollieren von Anfragen oder beim Übertragen von JSON zwischen Komponenten abzuschneiden. Berücksichtigen Sie außerdem Größenlimits auf Client-, Zwischenkomponenten- und Serverseite, denn eine Ablehnung kann erfolgen, bevor der Endpoint den Body verarbeitet.

• Typische Fehler: falscher Feldname, fehlerhaftes JSON, fehlender Boundary-Wert, abgeschnittener Base64-Inhalt und nicht akzeptierter MIME-Type.
• Protokollieren Sie nicht den vollständigen Dateiinhalt. Erfassen Sie nur die für die Diagnose notwendigen Metadaten, ohne das Dokument offenzulegen.

Ende-zu-Ende prüfen, ob die Datei unverändert ist

Eine erfolgreiche HTTP-Antwort beweist für sich genommen nicht, dass der gespeicherte Inhalt mit der Quelldatei übereinstimmt. Entwerfen Sie einen Test, bei dem Sie eine repräsentative Datei senden und das empfangene Objekt anschließend über den in der API dokumentierten Mechanismus abrufen. Gibt es keine dokumentierte Möglichkeit, die Datei abzurufen, klären Sie, welche Prüfung der Dienst anbietet. Nehmen Sie weder an, dass die Antwort die Datei enthält, noch dass es einen Download-Vorgang gibt. Bewahren Sie die unveränderte Testdatei auf und notieren Sie ihre Größe sowie, sofern der Ablauf dies ermöglicht, einen lokal berechneten Hashwert.

Vergleichen Sie die abgerufene Datei mit dem Original, indem Sie die Binärdaten direkt vergleichen oder für beide denselben Hashwert berechnen. Testen Sie mehrere für die Integration relevante Dateitypen und -größen, darunter kleine Dateien und solche nahe am dokumentierten Limit. Prüfen Sie außerdem den Antwortcode, den Fehler-Body und sichere Client-Protokolle. Weicht das Ergebnis ab, grenzen Sie ein, an welcher Stelle die Änderung aufgetreten ist: beim lokalen Einlesen, bei der Codierung, bei der Übertragung, bei der Serververarbeitung oder beim anschließenden Herunterladen.

• Testen Sie mindestens eine Binärdatei und eine Datei mit Textinhalt. Beziehen Sie Namen mit Leerzeichen oder Nicht-ASCII-Zeichen ein, sofern der Vertrag dies erlaubt.
• Wiederholen Sie Tests mit Dateien, die Limits überschreiten, nur in einer kontrollierten Umgebung. Stellen Sie sicher, dass die Ablehnung eindeutig ist und kein unvollständiges Objekt zurückbleibt.

Checkliste vor der Integration

Machen Sie vor dem Deployment aus dem Vertrag eine überprüfbare Checkliste: richtiger Vorgang und richtige Version, angegebener Content-Type, genaue Felder und Namen, erforderliche Authentifizierung, bekannte Limits und die Bedeutung der Antworten. Implementieren Sie die Anfrage mit einer Bibliothek, die Multipart korrekt verarbeitet, oder mit einer zuverlässigen JSON-Serialisierung. Legen Sie fest, was bei Netzwerkfehlern, Größenbegrenzungen, ungültigen Zugangsdaten oder fehlerhaften Antworten geschieht. Automatische Wiederholungsversuche für einen Upload sind nicht immer unproblematisch: Klären Sie, ob der Endpoint eine Wiederholung erlaubt, ohne Duplikate oder mehrdeutige Ergebnisse zu erzeugen.

Schließen Sie die Prüfung mit betrieblichen Sicherheitsmaßnahmen ab. Beschränken Sie den Zugriff auf die Quelldatei auf das für die Integration Erforderliche, vermeiden Sie Zugangsdaten oder sensible Inhalte in Protokollen und löschen Sie temporäre Dateien, sobald sie nicht mehr benötigt werden. Dokumentieren Sie, wie sich ein fehlgeschlagener Upload mit einer Testdatei reproduzieren und der Empfang überprüfen lässt. Apification bietet Integrationen für Cloud und seine Dienste über REST API, OpenAPI, Webhooks, iFrame und JavaScript. Die Details zu Uploads, Berechtigungen und Funktionen der einzelnen Endpoints müssen anhand der jeweils geltenden Dokumentation bestätigt werden und dürfen nicht aus dieser allgemeinen Möglichkeit abgeleitet werden.

• Vertrag geprüft und Version dokumentiert.
• Darstellung und Limits für den konkreten Endpoint bestätigt.
• Integritäts-, Fehler- und Wiederholungstests abgeschlossen.
• Zugriff, Protokolle und temporäre Dateien geprüft.

Häufige Fragen