NextPDF Connect — REST-Transport

Auf einen Blick

Der REST-Transport führt bin/nextpdf-server in einem RoadRunner-HTTP-Worker-Pool aus. Er wird durch ein OpenAPI-3.1-Dokument beschrieben, authentifiziert jede Anfrage mit Ausnahme von Health-Anfragen über einen Bearer-API-Schlüssel und stellt Pro- und Enterprise-Routen abhängig von der installierten Stufe bereit.

Installation

composer require nextpdf/server
./vendor/bin/rr get-binary

Konzeptioneller Überblick

Jede Anfrage durchläuft eine PSR-15-Middleware-Pipeline, bevor sie einen Handler erreicht. Die Pipeline übernimmt die Vergabe der Request-ID, Limits für Bodygröße und stufenabhängige Payload, CORS, Authentifizierung, Capability-Autorisierung, Rate-Limiting pro IP und pro Client, Idempotenz und ein Timeout. Eine PSR-15-Middleware, die die Antwort nicht selbst erzeugen kann, delegiert an den bereitgestellten Request-Handler (PSR-15 §2.2 MiddlewareInterface::process, Klausel psr_15_handlers#2.2.p14); die PSR-7-Request-Objekte, die die Pipeline weitergibt, sind unveränderlich — ein zustandsändernder Aufruf gibt eine neue Instanz zurück, statt das vorhandene Objekt direkt zu verändern (PSR-7 §3.2.1).

Die Routentabelle wird beim Start aufgebaut und hängt von der Laufzeitumgebung ab: Core-Routen sind immer registriert; die Pro-Operationsrouten werden nur registriert, wenn Pro oder Enterprise installiert ist; die Enterprise-Routen werden nur registriert, wenn Enterprise installiert ist. Session-Routen werden nur registriert, wenn Sessions aktiviert sind.

API-Oberfläche

Immer registrierte Routen

Methode	Pfad	Auth
GET	/healthz	keine (Liveness)
GET	/readyz	keine (Readiness)
POST	/api/v1/render	Bearer
GET	/api/v1/capabilities	Bearer
POST	/api/v1/jobs	Bearer
GET	/api/v1/jobs/{id}	Bearer
GET	/api/v1/jobs/{id}/result	Bearer
DELETE	/api/v1/jobs/{id}	Bearer
POST	/api/v1/extract-text · /merge · /split	Bearer

Die Health-Probes sind sichere, nur lesende Endpunkte: Sie verursachen keine Zustandsänderung; genau diese Eigenschaft definiert RFC 9110 für sichere Methoden (RFC 9110 §9.2.1).

Stufengesteuerte Routen (laufzeitabhängig)

Nur dann registriert, wenn das entsprechende Paket installiert ist:

• Pro oder Enterprise installiert: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
• Enterprise installiert: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

Eine Anfrage an eine Route, deren Stufe nicht installiert ist, wird nicht geroutet. Eine Anfrage, die mit einem Schlüssel authentifiziert wird, dessen Stufe unter der Stufe der Route liegt, wird mit 403 abgelehnt. Ist Signieren verfügbar, bietet NextPDF Connect mit Pro nur das Signieren nach PAdES Baseline-B (B-B); Long-Term-Validation-Profile gehören nicht zur Oberfläche dieses Transports.

OpenAPI-Vertrag

Die REST-Oberfläche wird als statisches OpenAPI-3.1-Dokument unter openapi/nextpdf-connect.yaml im Paket ausgeliefert. Das Security-Schema ist ein Bearer-API-Schlüssel im Authorization-Header (Bearer npk_live_{kid}_{secret}). Fehlerantworten sind RFC 7807-Problem-Details-Dokumente mit einer type-URL pro Bedingung.

OpenAPI-Rendering — Scalar

Gemäß §12 des Plans für die Dokumentationsplattform rendert die aggregierte Dokumentationsseite dieses OpenAPI-Dokument mit Scalar (@scalar/api-reference). Es wird als <ScalarApiReference src=…>-Komponente auf der REST-Integrationsseite eingebettet. Die Source of Truth ist die openapi/nextpdf-connect.yaml des Pakets. Der Site-Build bezieht und rendert sie, statt eine parallele Endpunktreferenz von Hand zu pflegen. Es ist kein Laufzeitendpunkt zur OpenAPI-Auslieferung Teil des Servers; das Dokument ist ein Buildzeit-Artefakt.

Codebeispiel — Schnellstart

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

Codebeispiel — Produktion

Führen Sie das kombinierte Profil aus, damit REST- und gRPC-Transport denselben Supervisor verwenden:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
./vendor/bin/rr serve -c .rr.full.yaml

Sonderfälle und Fallstricke

• Eine Stufenroute gibt 404 zurück, wenn das Paket fehlt. Die Route ist nicht registriert, daher findet der Router keinen Treffer. Das ist das erwartete Verhalten; es ist kein Authentifizierungsfehler.

• 401 versus 403. 401 bedeutet, dass kein gültiger Schlüssel vorliegt (und die Antwort trägt einen WWW-Authenticate: Bearer-Header, gemäß RFC 9110 §11.6.1). 403 bedeutet, dass ein gültiger Schlüssel vorliegt, dessen Stufe nicht zur Operation berechtigt ist.

• Sessions sind standardmäßig deaktiviert. Die /api/v1/sessions/...-Routen existieren nur, wenn NEXTPDF_SESSIONS_ENABLED=true gesetzt ist und Tools verfügbar sind.

• Risikoreiche Operationen bleiben durch ein Gate abgesichert. Ein REST-Aufruf, der ein ApprovalRequired-Tool ansteuert, durchläuft dasselbe Human-in-the-Loop-Gate wie MCP. Siehe /connect/hitl-risk-tiers/.

Performance

Jeder RoadRunner-Worker bearbeitet immer nur eine Anfrage gleichzeitig. Lange synchrone Renderings belegen einen Worker; nutzen Sie die asynchronen Job-Routen für lang laufende Arbeit, damit Worker freigegeben werden. Dimensionieren Sie den Pool anhand der beobachteten Latenz; siehe /connect/production-usage/.

Sicherheitshinweise

Terminieren Sie TLS vor dem REST-Listener; er verwendet bewusst Klartext-HTTP und erwartet einen vorgelagerten Terminator. Authentifizieren Sie sich mit einem ausreichend zufälligen npk_live_-Schlüssel, bewahren Sie Schlüssel außerhalb der Versionsverwaltung auf und bevorzugen Sie den zur Laufzeit neu ladbaren dateibasierten Key-Store. Siehe /connect/security-and-operations/.

Konformität

Aussage	Quelle	reference_id
401 MUSS eine WWW-Authenticate-Challenge tragen	RFC 9110 §11.6.1
Sichere Methoden sind nur lesend	RFC 9110 §9.2.1
PSR-7-Requests sind unveränderlich	PSR-7 §3.2.1
Middleware, die die Antwort nicht erzeugen kann, delegiert an den bereitgestellten Request-Handler	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Kommerzieller Kontext

Routen für Signieren, Redaction, Vergleich, Barrierefreiheit, Optimierung und Compliance sind nur verfügbar, wenn nextpdf/premium installiert ist. Das Authentifizierungsmodell bleibt unverändert; die Stufe des Schlüssels bestimmt den Zugriff.

Siehe auch

• /connect/quickstart/ — die ausführbare Render-Anfrage
• /connect/security-and-operations/ — Authentifizierung und TLS-Betriebsmodell
• /connect/production-usage/ — Jobs, Idempotenz, Rate-Limiting
• /transports/mcp/ · /transports/grpc/ — die anderen Transporte
• /connect/tool-catalog/ — wie das Routenset auf den Tool-Katalog abgebildet wird