NextPDF Connect — Trasporto REST

In breve

Il trasporto REST esegue bin/nextpdf-server in un pool di worker HTTP di RoadRunner. È descritto da un documento OpenAPI 3.1, autentica tramite una chiave API bearer ogni richiesta diversa dai controlli di integrità e subordina le route Pro ed Enterprise al livello di licenza installato.

Installazione

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

Panoramica concettuale

Ogni richiesta attraversa una pipeline di middleware PSR-15 prima di raggiungere un handler: assegnazione dell’ID di richiesta, limiti per livello sulla dimensione del corpo e del payload, CORS, autenticazione, autorizzazione delle capability, limitazione della frequenza per IP e per client, idempotenza e timeout. Un middleware PSR-15 che non è in grado di produrre direttamente la risposta delega all’handler di richiesta fornito (PSR-15 §2.2 MiddlewareInterface::process, clausola psr_15_handlers#2.2.p14); gli oggetti di richiesta PSR-7 che attraversano la pipeline sono immutabili: una chiamata che modifica lo stato restituisce una nuova istanza anziché modificare l’oggetto esistente (PSR-7 §3.2.1).

La tabella delle route viene costruita all’avvio e dipende dal runtime: le route core sono sempre registrate; le route per le operazioni Pro vengono registrate solo quando è installato Pro o Enterprise; le route Enterprise vengono registrate solo quando è installato Enterprise. Le route di sessione vengono registrate solo quando le sessioni sono abilitate.

Superficie API

Route sempre registrate

Metodo	Percorso	Auth
GET	/healthz	nessuna (liveness)
GET	/readyz	nessuna (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

Le probe di integrità sono endpoint di sola lettura basati su metodi sicuri: non provocano alcuna modifica di stato, proprietà che RFC 9110 definisce come metodo sicuro (RFC 9110 §9.2.1).

Route soggette al livello di licenza (dipendenti dal runtime)

Vengono registrate solo quando è installato il pacchetto corrispondente:

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

Una richiesta verso una route il cui livello non è installato non viene instradata. Una richiesta autenticata con una chiave il cui livello è inferiore a quello della route viene rifiutata con 403. Quando la firma è esposta, NextPDF Connect con Pro fornisce solo la firma PAdES baseline-B (B-B); i profili di convalida a lungo termine non fanno parte della superficie di questo trasporto.

Contratto OpenAPI

La superficie REST viene fornita come documento OpenAPI 3.1 statico in openapi/nextpdf-connect.yaml all’interno del pacchetto. Lo schema di sicurezza usa una chiave API bearer nell’header Authorization (Bearer npk_live_{kid}_{secret}). Le risposte di errore sono documenti problem-details RFC 7807 con un URL type per ogni condizione.

Rendering OpenAPI — Scalar

Come indicato al §12 del piano della piattaforma di documentazione, il sito aggregato della documentazione esegue il rendering di questo documento OpenAPI con Scalar (@scalar/api-reference). Il documento è incorporato come componente <ScalarApiReference src=…> nella pagina di integrazione REST. La fonte di verità è il file openapi/nextpdf-connect.yaml del pacchetto. La build del sito lo recupera e ne esegue il rendering anziché mantenere manualmente un riferimento parallelo agli endpoint. Nessun endpoint runtime che esponga OpenAPI fa parte del server; il documento è un artefatto generato in fase di build.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Eseguire il profilo combinato affinché i trasporti REST e gRPC condividano un unico supervisore:

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

Casi limite e insidie

• Una route vincolata a un livello restituisce 404 quando il pacchetto è assente. La route non è registrata, quindi il router non la riconosce. Si tratta di un comportamento previsto; non è un errore di autenticazione.

• 401 rispetto a 403. 401 indica che manca una chiave valida (e la risposta contiene un header WWW-Authenticate: Bearer, secondo RFC 9110 §11.6.1). 403 indica una chiave valida il cui livello non è abilitato all’operazione.

• Le sessioni sono disattivate per impostazione predefinita. Le route /api/v1/sessions/... esistono solo quando NEXTPDF_SESSIONS_ENABLED=true e gli strumenti sono disponibili.

• Le operazioni ad alto rischio rimangono comunque soggette a controllo. Una chiamata REST che invoca uno strumento ApprovalRequired passa attraverso lo stesso gate human-in-the-loop di MCP. Vedere /connect/hitl-risk-tiers/.

Prestazioni

Ogni worker di RoadRunner gestisce una sola richiesta alla volta. I rendering sincroni di lunga durata occupano un worker; usare le route dei job asincroni per i lavori lenti, in modo da liberare i worker. Dimensionare il pool in base alla latenza osservata; vedere /connect/production-usage/.

Note sulla sicurezza

Terminare il TLS davanti al listener REST; per progettazione, il listener usa HTTP in chiaro e prevede un terminatore a monte. Autenticare le richieste con una chiave npk_live_ sufficientemente casuale, archiviare le chiavi al di fuori del controllo del codice sorgente e preferire l’archivio di chiavi su file con ricaricamento a caldo. Vedere /connect/security-and-operations/.

Conformità

Affermazione	Fonte	reference_id
401 DEVE riportare l’header WWW-Authenticate come challenge	RFC 9110 §11.6.1
I metodi sicuri sono di sola lettura	RFC 9110 §9.2.1
Le richieste PSR-7 sono immutabili	PSR-7 §3.2.1
Un middleware che non è in grado di produrre la risposta delega all’handler di richiesta fornito	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Contesto commerciale

Le route di firma, oscuramento, confronto, accessibilità, ottimizzazione e conformità compaiono solo quando è installato nextpdf/premium. Il modello di autenticazione resta invariato; il livello della chiave determina l’accesso.

Vedere anche

• /connect/quickstart/ — richiesta di rendering pronta da eseguire
• /connect/security-and-operations/ — autenticazione e configurazione TLS
• /connect/production-usage/ — job, idempotenza, limitazione della frequenza
• /transports/mcp/ · /transports/grpc/ — gli altri trasporti
• /connect/tool-catalog/ — mappatura dell’insieme delle route sul catalogo degli strumenti