Riferimento API REST di Connect

In breve

NextPDF Connect espone il proprio registro degli strumenti su HTTP tramite un trasporto REST descritto da un contratto OpenAPI 3.1. Questa pagina documenta tale superficie: URL di base, modalità di autenticazione, gruppi di operazioni e modello di errore. La specifica completa leggibile dalla macchina è pubblicata per poter essere caricata in un esploratore interattivo, in un generatore di client o in un client per richieste, senza copiare nulla manualmente.

Per il catalogo degli strumenti indipendente dal trasporto (le stesse operazioni tramite Model Context Protocol e gRPC, oltre che REST), vedere il riferimento dell’API di Connect. Per la pipeline RoadRunner, la distribuzione e la configurazione dell’autenticazione, vedere la guida al trasporto REST.

URL di base e autenticazione

Il trasporto REST rimane in ascolto sull’host e sulla porta configurati per la distribuzione. In un’esecuzione locale corrisponde a http://localhost:8080; in produzione è l’indirizzo esposto davanti al pool di worker.

L’autenticazione avviene tramite token bearer. Inviare la chiave API nell’intestazione Authorization in ogni richiesta verso una route soggetta a controllo di livello:

curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

I probe di sola lettura per liveness e readiness non richiedono token.

Operazioni

La disponibilità dipende dal controllo di livello. Il core open source include le operazioni relative a documenti, rendering, sessioni e processi. Firma, compilazione di moduli, oscuramento, confronto, controllo dell’accessibilità e ottimizzazione richiedono un’edizione commerciale installata insieme al server. L’insieme autorevole per una determinata distribuzione viene restituito dall’endpoint delle funzionalità. Interrogarlo invece di presumere un elenco fisso.

Stato di salute e ciclo di vita

Metodo	Percorso	Scopo
GET	/healthz	Probe di liveness. Nessuna autenticazione.
GET	/readyz	Probe di readiness (dipendenze e pool di worker pronti). Nessuna autenticazione.
GET	/api/v1/capabilities	Strumenti e livelli effettivamente esposti da questa distribuzione. Interrogare prima questo endpoint.

Rendering e documenti

Metodo	Percorso	Scopo
POST	/api/v1/render	Eseguire il rendering di un documento da un elenco ordinato di operazioni e restituire il PDF.
POST	/api/v1/extract-text	Estrarre il contenuto testuale da un PDF.
POST	/api/v1/merge	Unire più input PDF in un unico documento.
POST	/api/v1/split	Suddividere un PDF in più documenti.

Processi asincroni

Metodo	Percorso	Scopo
POST	/api/v1/jobs	Inviare un’operazione di lunga durata come processo.
GET	/api/v1/jobs/{id}	Eseguire il polling dello stato del processo.
GET	/api/v1/jobs/{id}/result	Recuperare il risultato del processo completato.

Sessioni

Le sessioni mantengono aperto un documento tra più chiamate, così da costruirlo in modo incrementale ed eseguirne il rendering una sola volta alla fine.

Metodo	Percorso	Scopo
POST	/api/v1/sessions	Aprire una sessione.
GET / DELETE	/api/v1/sessions/{sessionId}	Ispezionare o chiudere una sessione.
POST	/api/v1/sessions/{sessionId}/pages	Aggiungere una pagina.
POST	/api/v1/sessions/{sessionId}/text	Aggiungere testo.
POST	/api/v1/sessions/{sessionId}/images	Aggiungere un’immagine.
POST	/api/v1/sessions/{sessionId}/tables	Aggiungere una tabella.
POST	/api/v1/sessions/{sessionId}/html	Aggiungere HTML sottoposto a rendering.
POST	/api/v1/sessions/{sessionId}/font	Impostare il font attivo.
POST	/api/v1/sessions/{sessionId}/render	Eseguire il rendering del documento della sessione.

Operazioni dell’edizione commerciale

Queste route vengono registrate solo quando è installata l’edizione commerciale corrispondente. Alcune sono soggette ad approvazione tramite il flusso di conferma human-in-the-loop; vedere i livelli di rischio.

Metodo	Percorso	Scopo
POST	/api/v1/sign	Applicare una firma digitale.
POST	/api/v1/fill-form	Compilare un modulo interattivo.
POST	/api/v1/redact	Oscurare il contenuto.
POST	/api/v1/compare	Confrontare due documenti PDF.
POST	/api/v1/check-accessibility	Eseguire un controllo strutturale dell’accessibilità.
POST	/api/v1/optimize	Ottimizzare un documento e ridurne le dimensioni.

Modello di errore

Il trasporto REST utilizza i codici di stato HTTP con la semantica definita da RFC 9110: 2xx per l’esito positivo, 4xx per una richiesta che il chiamante deve correggere (400 corpo non valido, 401 token mancante o non valido, 403 livello o approvazione negati, 404 route o processo sconosciuto, 409 conflitto di idempotenza, 422 richiesta ben formata che il motore non è in grado di elaborare) e 5xx per un errore lato server. Una risposta 401 contiene una challenge WWW-Authenticate.

I corpi di errore sono documenti application/problem+json conformi a RFC 9457 (Problem Details for HTTP APIs): un type stabile, un title breve, lo status numerico e un detail leggibile. Basare il confronto su type, non sulla stringa detail. Vedere anche RFC 9110 (HTTP Semantics) e RFC 9457 per le definizioni normative.

Inviare le richieste che modificano lo stato con un’intestazione Idempotency-Key, in modo che una richiesta ritentata venga elaborata una sola volta.

Specifica leggibile dalla macchina

Il contratto completo viene pubblicato come documento OpenAPI 3.1 statico:

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

Usarlo come unica fonte autorevole per la superficie REST:

1. Aprire l’esploratore API interattivo — un riferimento Scalar self-hosted nel browser, generato da questo contratto — per leggere e provare ogni operazione con i relativi schemi di richiesta e risposta.
2. Importarlo in un client per richieste come Postman o Insomnia.
3. Generare un client tipizzato per il proprio linguaggio tramite un generatore OpenAPI.

Il documento è un contratto statico, vincolato alla versione del pacchetto. Non è servito da un endpoint attivo, quindi rimane stabile tra le distribuzioni.

Vedere anche

• Riferimento dell’API di Connect — catalogo completo degli strumenti su MCP, REST e gRPC.
• Guida al trasporto REST — pipeline RoadRunner, autenticazione bearer e routing per livello.
• Panoramica di NextPDF Connect — che cos’è il server e come eseguirlo.