Sie haben einen Endpunkt erstellt, der eine Datei entgegennimmt. Ein Benutzer lädt ein Profilbild auf POST /avatars hoch, oder Ihre App sendet ein signiertes PDF an POST /documents. Die Route funktioniert in Ihrem Kopf. Nun müssen Sie beweisen, dass sie über HTTP funktioniert: Wählen Sie eine echte Datei aus, fügen Sie sie einem Formularfeld hinzu, senden Sie die Anfrage und überprüfen Sie die Antwort.
Hier werden viele API-Tools knifflig. Datei-Uploads verwenden multipart/form-data, nicht JSON, sodass Sie keinen Body einfügen und auf Senden klicken können. Sie benötigen einen Anfrage-Builder, der Dateifelder versteht, und einen Test-Runner, der die Datei finden kann, wenn der Test später ausgeführt wird. Apidog handhabt beides, und dieser Leitfaden zeigt den gesamten Weg: das Senden eines einzelnen Uploads, das Senden einer Datei zusammen mit JSON, das Überprüfen der Antwort und dann den ehrlichen Teil, vor dem niemand warnt, nämlich was passiert, wenn derselbe Upload-Schritt im Runner oder CLI ohne grafische Oberfläche ausgeführt wird und die Datei nicht finden kann. Wenn Sie zunächst den Hintergrund des Formats selbst erfahren möchten, behandelt der Leitfaden Datei-Upload in APIs, wie Multipart-Anfragen strukturiert sind. Die MDN-Referenz zu FormData ist ein guter Begleiter für die Browser-Seite.
Was multipart/form-data ist und warum Uploads es benötigen
Ein API-Anfrage-Body kann verschiedene Formen annehmen. Im Body-Bereich von Apidog können Sie form-data, x-www-form-urlencoded, JSON, XML, raw oder binary wählen. Meistens greift man zu JSON. Datei-Uploads sind die Ausnahme.
Der Body-Typ form-data entspricht dem Header Content-Type: multipart/form-data. Es ist das Format, das zum Hochladen von Dateien zusammen mit anderen Daten entwickelt wurde. Statt eines einzelnen Blobs wird der Body in Teile aufgeteilt, jedes mit seinem eigenen Namen und seinem eigenen Inhalt. Ein Teil kann ein einfacher String sein, wie eine Bildunterschrift, ein anderer Teil können die Rohbytes eines Bildes sein. Deshalb können ein Foto-Upload und seine Metadaten in derselben Anfrage übertragen werden.
Der nahe Verwandte ist x-www-form-urlencoded. Es sieht im Editor ähnlich aus, Schlüssel-Wert-Paare, die im Body gesendet werden, ist aber für einfache Formulare ohne Dateien gedacht. Wenn Ihr Endpunkt eine Datei entgegennimmt, ist form-data das Richtige für Sie. Greifen Sie nur dann zu x-www-form-urlencoded, wenn jedes Feld ein kurzer Skalar ist und keine Bytes beteiligt sind.
In form-data zeigt Apidog jeden Parameter als Schlüssel-Wert-Paar an, und jeder Parameter hat einen Typ: String, Integer, Datei usw. Dieser Parameter-Typ ist der ganze Trick. Setzen Sie ein Feld auf file und Apidog behandelt seinen Wert als anzuhängende Datei statt als zu sendenden Text.
Einzelnen Datei-Upload senden und die Antwort überprüfen
Angenommen, Sie testen POST /avatars. Es nimmt ein Feld, avatar, mit einem Bild entgegen und gibt JSON mit der gespeicherten URL zurück. Hier ist die Anleitung.
1. Öffnen Sie den Body-Bereich und wählen Sie form-data. Stellen Sie in Ihrem Endpunkt oder einer neuen Anfrage die Methode auf POST und die URL auf Ihre Avatars-Route ein. Öffnen Sie den Body-Tab und wählen Sie den form-data Body-Typ. Apidog setzt den Content-Type: multipart/form-data für Sie.
2. Fügen Sie den Dateiparameter hinzu und setzen Sie dessen Typ auf file. Fügen Sie einen Parameter mit dem Schlüssel avatar hinzu. Verwenden Sie neben dem Schlüssel den Typselektor, um seinen Typ von string auf file zu ändern. Die Wertzelle wird zu einer Dateiauswahl anstelle eines Textfeldes.
3. Klicken Sie auf Upload und wählen Sie eine lokale Datei aus. Klicken Sie auf Upload in der avatar-Zeile und wählen Sie ein Bild von Ihrem Computer aus, z.B. jane-profile.png. Apidog speichert den Pfad zu dieser Datei.
4. Senden Sie die Anfrage. Klicken Sie auf Senden. Apidog liest die Datei vom gespeicherten lokalen Pfad, erstellt den Multipart-Body und sendet ihn. Gut zu wissen: Apidog sendet die Datei in der Anfrage, speichert die Datei aber nicht in der Cloud. Es speichert nur den lokalen Pfad, nicht die Bytes. Dieses Detail ist später wichtig, also merken Sie es sich.
Ein erfolgreicher Aufruf liefert etwa Folgendes zurück:
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. Überprüfen Sie die Antwort. Eine Sendung, die 200 zurückgibt, ist allein kein bestandener Test. Fügen Sie Assertions hinzu, damit die Überprüfung real ist. In Apidog fügen Sie diese als Post-Request-Assertions am Endpunkt oder Szenario-Schritt hinzu. Im Klartext möchten Sie den Status und dass der Body eine nutzbare URL enthält, bestätigen:
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Diese entsprechen direkt der Assertions-Benutzeroberfläche von Apidog: eine Assertion für den Statuscode, eine für das Vorhandensein von JSONPath $.avatarUrl, eine für $.contentType. Wenn Sie neu bei Assertions sind, zeigt der Leitfaden API-Assertions den vollständigen Satz von Operatoren und wie JSONPath ein Feld adressiert.
Für einen schnellen Realitätscheck außerhalb des Tools sieht derselbe Upload in curl so aus:
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
Das Flag -F ist curl's Art, einen Multipart-Teil zu erstellen, und @ weist es an, Dateiinhalte zu lesen. Der form-data Dateiparameter von Apidog macht dasselbe mit einer Auswahlhilfe anstelle eines Flags.
Eine Datei und JSON zusammen senden
Echte Endpunkte nehmen selten eine reine Datei entgegen. POST /documents möchte möglicherweise die Datei plus Metadaten: einen Titel, eine Kategorie, vielleicht ein Tags-Array. Sie haben zwei saubere Möglichkeiten, dies in einer Multipart-Anfrage zu tun.
Der einfache Fall sind skalare Felder. Fügen Sie weitere form-data-Parameter neben Ihrem Dateifeld hinzu und belassen Sie sie als string oder integer. Ein title-String, ein category-String, eine file vom Typ file. Alle drei werden in derselben Anfrage gesendet.
Wenn die Metadaten strukturiert sind, wie ein verschachteltes Objekt oder ein Array, senden Sie sie als JSON innerhalb eines String-Teils. Fügen Sie einen form-data-Parameter namens metadata hinzu, behalten Sie seinen Typ als string bei und fügen Sie das JSON direkt in den Wert ein:
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
Die Anfrage hat also zwei Teile: file (Typ file), das q3-invoice.pdf enthält, und metadata (Typ string), das dieses JSON enthält. Der Server liest die Datei aus einem Teil und parst das JSON aus dem anderen. Viele öffentliche APIs nehmen Uploads genau auf diese Weise entgegen; die Stripe Datei-Upload-Dokumentation ist ein gutes Beispiel für einen echten Multipart-Endpunkt, der einen Dateiteil mit einfachen Feldern paart. Dieses Muster ist so verbreitet, dass es auch Postman-Benutzer betrifft; wenn Sie migrieren, lässt sich die Anleitung zum Hochladen einer Datei und von JSON-Daten in Postman sauber auf die form-data-Felder von Apidog übertragen.
Müssen Sie mehr als eine Datei anhängen? Fügen Sie einen weiteren Parameter vom Typ file hinzu. Ein POST /documents, der eine Hauptdatei und ein Miniaturbild akzeptiert, erhält zwei Dateizeilen, file und thumbnail, jede mit einem eigenen Upload-Button. Es gibt keinen speziellen Multi-Datei-Modus; Sie fügen einfach Dateityp-Parameter hinzu, bis Sie jeden Teil abgedeckt haben, den der Endpunkt erwartet.
Die Anfrage in ein wiederholbares Testszenario umwandeln
Eine einzelne Sendung beweist, dass der Endpunkt einmal funktioniert. Um Regressionen abzufangen, möchten Sie den Upload in einem gespeicherten Testszenario haben, das bei Bedarf oder nach Zeitplan ausgeführt wird. Verketten Sie die Schritte: Laden Sie den Avatar hoch, erfassen Sie die zurückgegebene id, rufen Sie dann GET /users/{id} auf und überprüfen Sie, ob die Avatar-URL persistent ist.
Erstellen Sie dies auf die gleiche Weise, wie Sie die einzelne Anfrage erstellt haben, und speichern Sie es dann als Schritt in einem Szenario. Der Leitfaden Wie man ein Testszenario mit Apidog schreibt behandelt die Verkettung von Schritten und das Übergeben von Werten zwischen Schritten. Sobald der Upload in einem Szenario existiert, können Sie es bei jeder Bereitstellung gegen die Staging-Umgebung ausführen, bedingte Verzweigungen mit bedingter Logik in API-Testszenarien hinzufügen oder es mit geplanten API-Tests zeitgesteuert ausführen.
Alles oben Genannte läuft einwandfrei auf Ihrem Rechner, da Ihr Rechner die Datei besitzt. Diese Annahme ist genau das, was als Nächstes schiefgeht.
Die Falle: Uploads, die woanders ausgeführt werden
Hier ist der Teil, den der glückliche Pfad verbirgt. Apidog speichert den Dateipfad, nicht die Datei. Auf Ihrem Laptop ist das unsichtbar, da der Pfad jedes Mal zu einer echten Datei führt. Sobald derselbe Schritt auf einer anderen Maschine ausgeführt wird, zeigt der Pfad ins Leere.
Dies werden Sie an zwei Stellen antreffen.
Teamzusammenarbeit. Wenn ein Teamkollege Ihre POST /avatars-Anfrage öffnet, sieht er den Dateiparameter und den von Ihnen gewählten Pfad, z.B. /Users/jane/pics/jane-profile.png. Sie können die Anfrage sehen, aber nicht senden, da diese Datei auf Ihrer Festplatte liegt, nicht auf ihrer. Der Pfad ist lokal zu der Maschine, die ihn ausgewählt hat.
Runner- und CLI-Ausführungen. Das ist der Punkt, der bei der Automatisierung Probleme bereitet. Ihr Upload-Szenario läuft lokal erfolgreich, Sie planen es im Runner oder starten es über die CLI, und der Datei-Upload-Schritt schlägt fehl. Mit Ihren Assertions stimmt nichts nicht. Der Runner kann einfach keine Datei unter dem Pfad finden, den Ihr Laptop gespeichert hat, da dieser Pfad auf dem Host des Runners nicht existiert.
Die Lösung leitet sich von der Ursache ab. Die Datei muss auf der sendenden Maschine existieren, und der Pfad des Schritts muss dorthin zeigen.
Für den Runner: Der Runner liest Dateien aus einem Host-Verzeichnis, das in sein Volume gemountet ist. Diesen Mount legen Sie fest, wenn Sie den Runner bereitstellen, mithilfe des -v Flags. Kopieren Sie Ihre Upload-Datei in dieses gemountete Host-Verzeichnis. Öffnen Sie dann die Details des Datei-Upload-Schritts im Szenario, klicken Sie oben rechts auf die Schaltfläche Batch Edit und ersetzen Sie den Wert des Dateifeldes durch den Pfad innerhalb des Runner-Verzeichnisses, zum Beispiel:
/opt/runner/jane-profile.png
Für die CLI: gleiches Prinzip. Legen Sie die Datei auf der CLI-Maschine ab, verwenden Sie dann Batch Edit für den Schritt, um den Pfad auf ihren Speicherort dort zu zeigen, zum Beispiel:
/opt/apidog/runner/jane-profile.png
Eleganter als Hardcoding: Verwenden Sie eine Variable. Anstatt einen festen Pfad im Schritt zu verwenden, ersetzen Sie den Wert durch eine Variable und setzen Sie den Wert der Variable auf den tatsächlichen Dateipfad pro Umgebung. Dann läuft dasselbe Szenario auf Ihrem Laptop, dem Runner und in CI, ohne dass der Schritt jedes Mal bearbeitet werden muss. Sie zeigen die Variable lokal auf /Users/jane/pics/jane-profile.png und auf dem Runner auf /opt/runner/jane-profile.png, und der Schritt selbst ändert sich nie.
Eine Voraussetzung, die klar genannt werden sollte: Der Runner erreicht nur Host-Dateien, die sich unter dem Verzeichnis befinden, das Sie zum Zeitpunkt der Bereitstellung mit -v gemountet haben. Wenn Ihre Datei nicht unter diesem Mount liegt, wird kein Pfad sie finden. Das ist ein Detail der Bereitstellungskonfiguration, keine Planbeschränkung. Die Apidog-Dokumentation zu Datei-Upload-Anfragen erläutert die Schritte zum Mounten und zur Massenbearbeitung, wenn Sie die kanonische Version wünschen.
Den Workflow mit der Apidog CLI automatisieren
Sobald Ihr Upload-Szenario gespeichert ist, können Sie es kopflos (headless) in CI ausführen. Installieren Sie die CLI und authentifizieren Sie sich:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Führen Sie dann das gespeicherte Szenario anhand der ID aus und weisen Sie es einer Umgebung zu:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Hier ist -t die ID des Testszenarios, -e ist die Umgebungs-ID und -r ist der Reporter (verwenden Sie cli, html oder junit, durch Komma getrennt für mehrere). Die CLI führt Ihre gespeicherten Szenarien aus dem Cloud-Projekt aus und meldet Erfolg/Misserfolg mit Exit-Codes, was es ermöglicht, eine Pipeline zu steuern. Die Einrichtungsdetails finden Sie im Apidog CLI Installationsleitfaden.
Ein ehrlicher Hinweis, und es ist derselbe wie im letzten Abschnitt: Ein Szenario mit einem Datei-Upload-Schritt benötigt die Datei auf der CLI-Maschine, und der Pfad des Schritts muss dorthin zeigen. Legen Sie die Datei auf dem Runner ab, bearbeiten Sie dann den Pfad (Batch Edit) (oder verwenden Sie eine Variable) vor der Ausführung. Wenn Sie dies überspringen, schlägt der Upload-Schritt fehl, die Datei zu finden, auch wenn der Rest des Szenarios in Ordnung ist. Für eine umfassendere CI-Einrichtung, einschließlich der Übergabe von zeilenweisen Eingaben, siehe datengesteuertes Testen mit der Apidog CLI.
Häufig gestellte Fragen (FAQ)
Warum kann mein Teamkollege meine Datei-Upload-Anfrage nicht senden? Apidog speichert den lokalen Dateipfad, nicht die Datei selbst, und lädt die Datei niemals in die Cloud hoch. Ihr Teamkollege sieht die Anfrage und den von Ihnen gewählten Pfad, aber dieser Pfad verweist auf eine Datei auf Ihrer Festplatte, nicht auf seiner. Lassen Sie sie eine Kopie der Datei auf ihren Computer legen und das Feld auf ihren eigenen Pfad verweisen. Dieselbe Mechanik erklärt, warum geplante Tests und Runner-Jobs die Datei dort bereitgestellt benötigen, wo sie ausgeführt werden.
Wie sende ich JSON zusammen mit einer Datei in derselben Anfrage? Behalten Sie den Body-Typ als form-data bei. Fügen Sie Ihr Dateifeld mit dem Typ file hinzu, fügen Sie dann einen weiteren Parameter mit dem Typ string hinzu und fügen Sie das JSON in dessen Wert ein. Der Server erhält beide Teile in einer Multipart-Anfrage: die Datei in einem Teil, den JSON-String in einem anderen. Dies ist die Standardmethode, um Metadaten an einen Upload anzuhängen.
Welchen Pfad sollte ich für eine Datei im Runner verwenden? Verwenden Sie einen Pfad innerhalb des Host-Verzeichnisses, das Sie zum Zeitpunkt der Bereitstellung mit dem -v Flag in das Volume des Runners gemountet haben, zum Beispiel /opt/runner/yourfile.jpg. Kopieren Sie die Datei in dieses gemountete Verzeichnis, öffnen Sie dann den Schritt, klicken Sie auf Batch Edit und setzen Sie den Wert des Feldes auf diesen Pfad. Das CLI-Äquivalent sieht so aus: /opt/apidog/runner/yourfile.jpg.
Gibt es ein Dateigrößenlimit oder eine Liste zulässiger Dateitypen? Das Upload-Verhalten in Apidog betrifft, wie die Anfrage aufgebaut wird und woher die Datei gelesen wird. Ihre tatsächlichen Größen- und Typbeschränkungen stammen von der API, die Sie testen. Überprüfen Sie daher die Validierungsregeln Ihres Servers und schreiben Sie Assertions gegen die Antworten, die er für überdimensionierte oder abgelehnte Dateien zurückgibt.
Sollte ich form-data oder x-www-form-urlencoded für Uploads verwenden? Verwenden Sie form-data. Es entspricht multipart/form-data und ist dafür gebaut, Dateien zu übertragen. x-www-form-urlencoded ist für einfache Formulare mit kurzen skalaren Feldern ohne Datei, daher wird es Ihr Bild oder PDF nicht übertragen.
Zusammenfassung
Das Testen von Datei-Uploads läuft auf zwei Dinge hinaus: die Multipart-Anfrage richtig aufbauen und sicherstellen, dass die Datei erreichbar ist, wo immer der Test ausgeführt wird. In Apidog setzen Sie den Body auf form-data, ändern den Typ Ihres Feldes auf file, klicken auf Upload, fügen optional JSON als String-Teil hinzu, senden und überprüfen dann. Wenn Sie dasselbe Szenario zum Runner oder zur CLI verschieben, stellen Sie die Datei auf dieser Maschine bereit und passen Sie den Pfad mit Batch Edit oder einer Variable an, und die automatisierte Ausführung verhält sich wie Ihre lokale.
Möchten Sie es an Ihrem eigenen Endpunkt ausprobieren? Laden Sie Apidog herunter, richten Sie eine form-data-Anfrage an Ihre Upload-Route und beobachten Sie die zurückkommende Antwort. Der Start ist kostenlos, keine Kreditkarte erforderlich.