PDF Blocks
PreiseSupport
Kostenlos starten
Seite öffnen

Anfragen und Antworten

Die Form, die jeder Aufruf teilt: eine Anfrage als Multipart-Formular, eine Antwort, die das Dokument ist, und kein Zustand dazwischen.

Jede Aktion der API teilt denselben Vertrag. Sie senden eine Anfrage vom Typ multipart/form-data mit Ihrem PDF im Feld file und erhalten das verarbeitete Dokument als Antworttext zurück. Es gibt keinen Auftrag abzufragen, keinen Schritt zum Hochladen und danach keine Ressource aufzuräumen: eine Anfrage hinein, ein Dokument heraus. Lernen Sie diese Form einmal, und jede Seite einer Aktion liest sich gleich.

Jede Anfrage sieht gleich aus

Jede Aktion ist ein einzelnes POST an /v1/<action> mit einem Anfragetext vom Typ multipart/form-data. Drei Dinge sind immer vorhanden:

  • Der Header X-API-Key, der Ihren geheimen Schlüssel trägt, über HTTPS.
  • Ein Teil file, der das PDF-Eingabedokument enthält.
  • Null oder mehr Teile mit Zeichenketten für die Optionen der Aktion, zum Beispiel line_1 oder pages, genau so benannt, wie die Referenz der Aktion sie auflistet.

Hier eine vollständige Anfrage, die ein Wasserzeichen aufbringt, als reines HTTP dargestellt:

POST /v1/add_text_watermark HTTP/1.1
Host: api.pdfblocks.com
X-API-Key: your_api_key
Content-Type: multipart/form-data; boundary=----PdfBlocksBoundary

------PdfBlocksBoundary
Content-Disposition: form-data; name="file"; filename="input.pdf"
Content-Type: application/pdf

%PDF-1.7
<binary PDF bytes>
------PdfBlocksBoundary
Content-Disposition: form-data; name="line_1"

CONFIDENTIAL
------PdfBlocksBoundary--

Teil für Teil gelesen:

  • Anfragezeile: POST /v1/add_text_watermark. Der Name der Aktion ist der Pfad, die Methode ist immer POST.
  • X-API-Key: Ihr Schlüssel authentifiziert die Anfrage. Siehe Authentifizierung.
  • Content-Type: multipart/form-data mit einer Grenzzeichenkette. Die Multipart-Hilfe jedes HTTP-Clients setzt diesen Header und die Grenze für Sie; von Hand schreiben Sie ihn selten.
  • Der Teil file: das PDF-Eingabedokument, binär gesendet.
  • Teile für Optionen: ein Teil pro Option, hier line_1. Jeder ist ein einfacher Zeichenkettenwert.

Diesen Anfragetext bauen Sie nie selbst zusammen. Der HTTP-Client jeder Sprache erstellt ihn aus einem Datei-Handle und ein paar Feldern. Dieselbe Anfrage in cURL:

cURLbash
curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F line_1='CONFIDENTIAL' \
  -o watermarked.pdf

Die voreingestellte Basis-URL ist https://api.pdfblocks.com. Um die Verarbeitung in einer bestimmten Rechtsordnung zu halten, tauschen Sie den Host gegen einen regionalen aus. Siehe Regionen und Datenresidenz. Nur der Host ändert sich; Pfad, Header und Anfragetext sind überall identisch.

Jede Antwort ist das Dokument

Eine Aktion mit einer einzelnen Ausgabe antwortet mit 200 OK und dem verarbeiteten PDF als reinem Antworttext:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 48213

%PDF-1.7
<binary PDF bytes>

Der Antworttext ist das fertige Dokument, kein JSON, das eine URL umschließt, und keine base64-Zeichenkette. Verarbeiten Sie ihn als Stream direkt in eine Datei, oder geben Sie ihn an den nächsten Schritt Ihrer Pipeline weiter. In cURL ist das oben das -o watermarked.pdf; im Code ist es das Schreiben der Bytes von response auf die Festplatte, genau wie es die Beispiele auf jeder Seite einer Aktion tun.

Bewusst stateless

Die API speichert nichts. Ihr Dokument wird im Arbeitsspeicher verarbeitet, in der Region, die Sie ansprechen, und verworfen, sobald die Antwort geschrieben ist. Es gibt keine Dokument-ID, auf die Sie später verweisen könnten, und keine serverseitige Kopie zum Löschen. Da zwischen den Aufrufen nichts bestehen bleibt, muss jede Anfrage ihre eigene Eingabe file mitführen, auch wenn Sie Aktionen verketten und die Ausgabe eines Aufrufs direkt in den nächsten geben (siehe Aktionen verketten).

Wo der Vertrag variiert

Drei Dinge setzen auf dieser Grundlage auf, jedes auf einer eigenen Seite dokumentiert:

  • Mehr als eine Eingabe. Dokumente zusammenführen nimmt ein geordnetes Array von Teilen file entgegen, und Bildwasserzeichen hinzufügen nimmt einen zweiten binären Teil image entgegen. Beides ist unter Mit Dateien arbeiten beschrieben.
  • Mehr als eine Ausgabe. Die Familie der Aktionen zum Aufteilen gibt mehrere Dokumente zurück, und Sie wählen die Verpackung (ZIP, JSON oder Multipart) mit dem Header Accept. Siehe Antwortformate.
  • Fehlschläge. Jeder Fehler gibt einen Antworttext vom Typ application/problem+json gemäß RFC 7807 zurück, niemals ein unvollständiges PDF. Siehe Fehler.