Wie Du Ein Base64-PDF in Einer JSON-API-Anfrage Verwendest

REST- und JSON-APIs sind um Text aufgebaut, nicht um rohes Binär, daher gibt es keine native Möglichkeit, die Bytes eines PDFs direkt in ein JSON-Feld zu legen. Indem die Datei zuerst als Base64 kodiert wird, entsteht ein String, den JSON wie jeden anderen Textwert behandelt.

Falls du noch keine Datei umgewandelt hast, deckt der PDF-zu-Base64-Leitfaden den eigentlichen Konvertierungsschritt ab.

Eine typische Anfrage kombiniert den kodierten String mit ein paar Metadatenfeldern: ein Feld — oft file, document oder content genannt — enthält den Base64-Text, ein filename-Feld trägt den ursprünglichen Dateinamen, und ein contentType- oder mimeType-Feld, gesetzt auf application/pdf, sagt dem Empfänger, wie die Bytes nach dem Dekodieren zu interpretieren sind.

Halte das kodierte Feld als einen einzigen, ununterbrochenen String. Zeilenumbrüche oder zusätzliche Leerzeichen, die ein Editor oder ein Kopier-Schritt einfügt, beschädigen den Wert, bevor er überhaupt den Server erreicht.

Die meisten HTTP-Clients — fetch im Browser, eine serverseitige HTTP-Bibliothek oder ein Tool wie curl — senden den JSON-Body genauso wie jeden anderen Payload, solange der Content-Type-Header auf application/json gesetzt ist. Das Base64-Feld ist einfach ein langer String innerhalb dieses Bodys.

Behalte die Gesamtgröße der Anfrage im Blick: Das kodierte PDF ist Teil des JSON, also erhöht ein großer Anhang die Body-Größe direkt, und manche API-Gateways oder Reverse-Proxys erzwingen eine maximale Anfragegröße.

Die meisten serverseitigen Sprachen bringen einen eingebauten Base64-Decoder mit. Das Dekodieren verwandelt den String zurück in die exakten Original-Bytes, die der Server dann auf die Festplatte schreiben, in einer Datenbank speichern, an einen anderen Dienst weiterleiten oder zurück an einen Client streamen kann.

Wenn die dekodierte Datei sich nicht als gültiges PDF öffnen lässt, prüfe auf ein übrig gebliebenes Data-URI-Präfix oder Kopier-Fehler — siehe häufige Probleme bei PDF zu Base64.

Für große PDFs, häufige Uploads oder Dateien, die gestreamt statt vollständig im Speicher gehalten werden müssen, ist ein Multipart-Datei-Upload oder ein direkter Upload in einen Speicher meist die bessere Wahl, als die Datei in JSON einzubetten. Base64 in JSON funktioniert am besten für kleine bis mittelgroße Dateien, die gelegentlich bewegt werden — Zertifikate, unterschriebene Formulare, kurze Berichte.