DEV Community

Cover image for Wie man Dateiupload-APIs (multipart/form-data) in Apidog testet
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Wie man Dateiupload-APIs (multipart/form-data) in Apidog testet

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. Jetzt müssen Sie den Request über HTTP testen: Datei auswählen, Formularfeld befüllen, Anfrage senden und Antwort prüfen.

Apidog noch heute ausprobieren

Datei-Uploads verwenden multipart/form-data, nicht JSON. Deshalb reicht es nicht, einen JSON-Body einzufügen und auf „Senden“ zu klicken. Sie benötigen einen Request-Builder mit Dateifeldern – und für automatisierte Tests einen Runner, der die Datei auch auf dem Ausführungsrechner findet. Apidog unterstützt beides. Dieser Leitfaden zeigt:

  • einen einzelnen Datei-Upload,
  • Datei und JSON in derselben Anfrage,
  • Assertions für die Antwort,
  • Datei-Pfade für Runner, CLI und CI.

Für Hintergrundwissen zum Format siehe Datei-Upload in APIs. Für die Browser-Seite ist die MDN-Referenz zu FormData hilfreich.

Was multipart/form-data ist und warum Uploads es benötigen

Ein API-Request-Body kann viele Formate haben: form-data, x-www-form-urlencoded, JSON, XML, raw oder binary. Für die meisten APIs ist JSON die Standardwahl. Bei Datei-Uploads ist das anders.

Der Body-Typ form-data erzeugt einen Request mit:

Content-Type: multipart/form-data
Enter fullscreen mode Exit fullscreen mode

Der Request-Body besteht aus mehreren Teilen. Jeder Teil besitzt einen Namen und eigenen Inhalt:

  • ein Teil kann ein String sein, etwa title,
  • ein Teil kann die Rohbytes einer Datei enthalten, etwa avatar.

So lassen sich Datei und Metadaten in einem Request übertragen.

x-www-form-urlencoded sieht im Editor ähnlich aus, ist aber nur für einfache Schlüssel-Wert-Paare ohne Dateien gedacht. Sobald Ihr Endpunkt ein Bild, PDF oder andere Binärdaten erwartet, verwenden Sie form-data.

In Apidog hat jeder form-data-Parameter einen Typ, beispielsweise string, integer oder file. Der Typ file sorgt dafür, dass Apidog die ausgewählte Datei anhängt, statt ihren Pfad als Text zu senden.

Einzelnen Datei-Upload senden und die Antwort überprüfen

Angenommen, Sie testen:

POST /avatars
Enter fullscreen mode Exit fullscreen mode

Der Endpunkt erwartet das Feld avatar mit einem Bild und liefert eine gespeicherte URL zurück.

1. Request konfigurieren

Setzen Sie die Methode auf POST und tragen Sie die URL Ihrer Upload-Route ein:

POST https://api.example.com/avatars
Enter fullscreen mode Exit fullscreen mode

Öffnen Sie den Body-Tab und wählen Sie form-data. Apidog setzt den passenden multipart/form-data-Header automatisch.

2. Dateifeld anlegen

Fügen Sie einen Parameter hinzu:

Schlüssel Typ Wert
avatar file lokale Bilddatei

Ändern Sie den Typ des Felds von string auf file. Das Wertfeld wird dadurch zur Dateiauswahl.

3. Datei auswählen

Klicken Sie in der Zeile avatar auf Upload und wählen Sie beispielsweise:

jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Apidog speichert dabei den lokalen Pfad zur Datei.

4. Anfrage senden

Klicken Sie auf Senden. Apidog liest die Datei vom lokalen Pfad, erstellt den Multipart-Body und sendet ihn an den Server.

Ein erfolgreicher Response könnte so aussehen:

{
  "id": "usr_8842",
  "avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
  "sizeBytes": 48210,
  "contentType": "image/png"
}
Enter fullscreen mode Exit fullscreen mode

Wichtig: Apidog speichert nicht die Datei in der Cloud, sondern nur ihren lokalen Pfad. Das ist für Runner und CLI später entscheidend.

5. Assertions hinzufügen

Ein Status 200 allein ist kein vollständiger Test. Prüfen Sie zusätzlich, ob die API die erwarteten Daten zurückliefert.

Fügen Sie als Post-Request-Assertions hinzu:

status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Enter fullscreen mode Exit fullscreen mode

Damit prüfen Sie:

  1. Der Request war erfolgreich.
  2. Die Antwort enthält eine Avatar-URL.
  3. Der Server hat den erwarteten Content-Type verarbeitet.

Weitere Operatoren und JSONPath-Beispiele finden Sie im Leitfaden zu API-Assertions.

Zum Vergleich sieht derselbe Upload mit curl so aus:

curl -X POST https://api.example.com/avatars \
  -F "avatar=@jane-profile.png"
Enter fullscreen mode Exit fullscreen mode

-F erzeugt einen Multipart-Teil. Das @ weist curl an, den Inhalt der Datei zu lesen.

Eine Datei und JSON zusammen senden

Produktive Upload-Endpunkte erwarten oft mehr als nur eine Datei. Beispielsweise könnte POST /documents Folgendes benötigen:

  • eine PDF-Datei,
  • einen Titel,
  • eine Kategorie,
  • Tags oder weitere Metadaten.

Einfache Metadaten als zusätzliche Felder

Für skalare Werte legen Sie weitere form-data-Parameter an:

Schlüssel Typ Beispielwert
file file q3-invoice.pdf
title string Q3 Invoice
category string billing

Alle Felder werden im selben Multipart-Request gesendet.

Strukturiertes JSON als String-Feld senden

Für verschachtelte Daten oder Arrays senden Sie JSON in einem string-Teil. Fügen Sie einen Parameter metadata hinzu, behalten Sie den Typ string bei und verwenden Sie beispielsweise diesen Wert:

{
  "title": "Q3 Invoice",
  "category": "billing",
  "tags": ["invoice", "2026", "paid"]
}
Enter fullscreen mode Exit fullscreen mode

Der Request enthält dann zwei relevante Teile:

file      → Typ: file
metadata  → Typ: string, enthält JSON
Enter fullscreen mode Exit fullscreen mode

Der Server liest die Datei aus dem ersten Teil und parst den JSON-String aus dem zweiten. Dieses Muster wird von vielen APIs verwendet. Ein Beispiel aus der Praxis ist die Stripe-Dokumentation für Datei-Uploads.

Wenn Sie von Postman migrieren, können Sie die Anleitung zum Hochladen einer Datei und von JSON-Daten in Postman direkt auf die form-data-Felder in Apidog übertragen.

Mehrere Dateien senden

Für mehrere Dateien benötigen Sie keinen speziellen Multi-Upload-Modus. Fügen Sie einfach pro Datei ein weiteres Feld vom Typ file hinzu:

Schlüssel Typ
file file
thumbnail file

Jede Datei erhält eine eigene Upload-Auswahl.

Die Anfrage in ein wiederholbares Testszenario umwandeln

Ein manueller Request zeigt nur, dass der Upload einmal funktioniert. Für Regressionstests speichern Sie den Ablauf als Szenario.

Ein typisches Szenario kann so aussehen:

  1. POST /avatars ausführen.
  2. Die zurückgegebene id speichern.
  3. GET /users/{id} aufrufen.
  4. Prüfen, ob die Avatar-URL weiterhin vorhanden ist.

Erstellen Sie den Upload-Request wie oben und speichern Sie ihn anschließend als Szenario-Schritt. Der Leitfaden Wie man ein Testszenario mit Apidog schreibt zeigt, wie Sie Schritte verketten und Werte zwischen ihnen übergeben.

Danach können Sie das Szenario:

Lokal funktioniert das, weil die ausgewählte Datei auf Ihrem Rechner existiert. Genau diese Annahme wird bei automatisierten Ausführungen relevant.

Die Falle: Uploads auf anderen Maschinen ausführen

Apidog speichert den Dateipfad, nicht die Datei selbst. Auf Ihrem Laptop ist das unauffällig, weil der Pfad auf eine vorhandene Datei verweist.

Wird derselbe Request auf einer anderen Maschine ausgeführt, kann dieser Pfad ungültig sein.

Teamzusammenarbeit

Ein Teamkollege kann Ihren Request öffnen und sieht beispielsweise diesen Pfad:

/Users/jane/pics/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Die Datei liegt aber auf Ihrer Festplatte, nicht auf seiner. Der Request ist sichtbar, kann aber nicht erfolgreich ausgeführt werden, bevor die Datei lokal bereitgestellt und ein gültiger Pfad eingetragen wurde.

Runner und CLI

Dasselbe Problem tritt bei Runner-, CLI- oder CI-Ausführungen auf:

  • Das Szenario funktioniert lokal.
  • Der Runner startet den Upload-Schritt.
  • Der gespeicherte Pfad existiert auf dem Runner-Host nicht.
  • Der Upload schlägt fehl, bevor Ihre API erreicht wird.

Die Lösung ist immer gleich: Die Datei muss auf der ausführenden Maschine vorhanden sein, und der konfigurierte Pfad muss auf diese Datei zeigen.

Datei für den Runner bereitstellen

Der Runner liest Dateien aus einem Host-Verzeichnis, das Sie beim Deployment über -v in sein Volume mounten.

Vorgehen:

  1. Mounten Sie ein Host-Verzeichnis beim Start des Runners.
  2. Kopieren Sie die Upload-Datei in dieses Verzeichnis.
  3. Öffnen Sie den Upload-Schritt im Szenario.
  4. Klicken Sie oben rechts auf Batch Edit.
  5. Ersetzen Sie den Wert des Dateifelds durch den Pfad im Runner-Verzeichnis.

Beispiel:

/opt/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Datei für die CLI bereitstellen

Für die CLI gilt dasselbe Prinzip:

  1. Legen Sie die Datei auf der Maschine ab, auf der die CLI läuft.
  2. Bearbeiten Sie den Dateipfad im Szenario mit Batch Edit.
  3. Verwenden Sie einen Pfad, der auf dieser Maschine existiert.

Beispiel:

/opt/apidog/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Besser als Hardcoding: Variablen verwenden

Verwenden Sie statt eines festen Pfads eine Umgebungsvariable. So bleibt der Szenario-Schritt unverändert, während jede Umgebung ihren eigenen Dateipfad erhält.

Beispiel:

Lokale Umgebung:
FILE_PATH=/Users/jane/pics/jane-profile.png

Runner-Umgebung:
FILE_PATH=/opt/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Im Upload-Schritt referenzieren Sie dann die Variable statt eines festen Pfads.

Dadurch kann dasselbe Szenario auf dem Laptop, im Runner und in CI laufen, ohne dass Sie den Schritt jeweils manuell bearbeiten müssen.

Der Runner kann nur auf Dateien zugreifen, die sich unter einem beim Deployment mit -v gemounteten Verzeichnis befinden. Liegt die Datei außerhalb dieses Mounts, hilft auch ein korrekter Pfad nicht weiter. Weitere Details finden Sie in der Apidog-Dokumentation zu Datei-Upload-Anfragen.

Den Workflow mit der Apidog CLI automatisieren

Sobald das Upload-Szenario gespeichert ist, können Sie es 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>
Enter fullscreen mode Exit fullscreen mode

Starten Sie anschließend ein gespeichertes Szenario mit Szenario- und Umgebungs-ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Die Optionen bedeuten:

Option Bedeutung
-t ID des Testszenarios
-e ID der Umgebung
-r Reporter, z. B. cli, html oder junit

Mehrere Reporter können kommagetrennt angegeben werden. Die CLI meldet Erfolg oder Fehler über Exit-Codes und kann damit eine CI-Pipeline steuern.

Die vollständige Einrichtung beschreibt der Apidog CLI Installationsleitfaden.

Auch in CI bleibt die wichtigste Regel bestehen: Die Upload-Datei muss auf der CLI-Maschine vorhanden sein, und der konfigurierte Pfad muss dorthin zeigen. Nutzen Sie Batch Edit oder besser eine Umgebungsvariable, bevor Sie das Szenario starten.

Für zeilenweise Eingaben und weitere CI-Setups siehe datengesteuertes Testen mit der Apidog CLI.

Häufig gestellte Fragen

Warum kann mein Teamkollege meine Datei-Upload-Anfrage nicht senden?

Apidog speichert den lokalen Dateipfad, nicht die Datei. Ihr Teamkollege sieht daher möglicherweise einen Pfad auf Ihrer Festplatte, der auf seinem Rechner nicht existiert.

Lösung:

  1. Datei auf dem Rechner des Teamkollegen bereitstellen.
  2. Den Dateipfad im Request auf den lokalen Speicherort ändern.

Dasselbe gilt für geplante Tests, Runner und CI.

Wie sende ich JSON zusammen mit einer Datei?

Verwenden Sie weiterhin form-data:

  1. Fügen Sie das Dateifeld mit Typ file hinzu.
  2. Fügen Sie ein weiteres Feld mit Typ string hinzu.
  3. Tragen Sie das JSON in dieses String-Feld ein.

Der Server erhält die Datei und den JSON-String als getrennte Teile derselben Multipart-Anfrage.

Welchen Pfad sollte ich im Runner verwenden?

Verwenden Sie einen Pfad innerhalb des Host-Verzeichnisses, das beim Runner-Deployment per -v gemountet wurde.

Beispiel:

/opt/runner/yourfile.jpg
Enter fullscreen mode Exit fullscreen mode

Kopieren Sie die Datei in dieses Verzeichnis und setzen Sie anschließend den Wert im Upload-Schritt über Batch Edit.

Für die CLI kann der Pfad beispielsweise so aussehen:

/opt/apidog/runner/yourfile.jpg
Enter fullscreen mode Exit fullscreen mode

Gibt es ein Dateigrößenlimit oder erlaubte Dateitypen?

Apidog bestimmt, wie der Multipart-Request aufgebaut wird und von wo die Datei gelesen wird. Größenlimits und erlaubte Dateitypen werden dagegen von der API festgelegt, die Sie testen.

Prüfen Sie daher die Server-Validierung und schreiben Sie Tests für Fehlerfälle, etwa:

  • Datei zu groß,
  • nicht unterstützter MIME-Type,
  • fehlendes Dateifeld,
  • beschädigte Datei.

Sollte ich form-data oder x-www-form-urlencoded verwenden?

Für Datei-Uploads verwenden Sie form-data.

form-data entspricht multipart/form-data und kann Binärdateien übertragen. x-www-form-urlencoded ist nur für kurze skalare Felder ohne Datei geeignet.

Zusammenfassung

Ein zuverlässiger Datei-Upload-Test besteht aus zwei Teilen:

  1. Multipart-Anfrage korrekt aufbauen.
  2. Sicherstellen, dass die Datei auf jeder Ausführungsmaschine erreichbar ist.

In Apidog setzen Sie den Body auf form-data, ändern den Feldtyp auf file, wählen die Datei aus, ergänzen bei Bedarf JSON als String-Feld und definieren Assertions für die Antwort.

Wenn Sie das Szenario im Runner, über die CLI oder in CI ausführen, stellen Sie die Datei auf dieser Maschine bereit. Aktualisieren Sie den Pfad über Batch Edit oder verwenden Sie eine Umgebungsvariable, damit derselbe Test in jeder Umgebung funktioniert.

Möchten Sie den Ablauf an Ihrer eigenen Upload-Route testen? Laden Sie Apidog herunter, erstellen Sie eine form-data-Anfrage und prüfen Sie den Response Ihres Endpunkts.

Top comments (0)