Référence de l'API REST Connect

En bref

NextPDF Connect expose son registre d’outils via HTTP, au moyen d’un transport REST décrit par un contrat OpenAPI 3.1. Cette page sert de référence pour cette surface : URL de base, authentification, groupes d’opérations et modèle d’erreur. La spécification complète, lisible par machine, est publiée afin que tu puisses la charger dans un explorateur interactif, un générateur de client ou un client de requêtes sans rien recopier à la main.

Pour le catalogue d’outils indépendant du transport (les mêmes opérations sur Model Context Protocol, gRPC et REST), consulte la référence de l’API Connect. Pour le pipeline RoadRunner, le déploiement et la configuration de l’authentification, consulte le guide du transport REST.

URL de base et authentification

Le transport REST écoute sur l’hôte et le port configurés pour ton déploiement. En local, c’est http://localhost:8080 ; en production, c’est l’adresse qui se trouve devant ton pool de workers.

L’authentification repose sur un jeton porteur. Envoie la clé d’API dans l’en-tête Authorization de chaque requête vers une route contrôlée par le niveau :

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"}]}'

Les sondes de disponibilité (liveness) et de préparation (readiness) en lecture seule ne nécessitent aucun jeton.

Opérations

La disponibilité des opérations dépend du niveau. Le cœur open source fournit les opérations de document, de rendu, de session et de job. La signature, le remplissage de formulaire, le caviardage, la comparaison, la vérification d’accessibilité et l’optimisation requièrent une édition commerciale installée aux côtés du serveur. Pour un déploiement donné, la liste faisant autorité est celle renvoyée par le point de terminaison des capacités. Interroge-le plutôt que de supposer une liste figée.

Santé et cycle de vie

Méthode	Chemin	Objectif
GET	/healthz	Sonde de disponibilité (liveness). Pas d’authentification.
GET	/readyz	Sonde de préparation (readiness) (dépendances et pool de workers prêts). Pas d’authentification.
GET	/api/v1/capabilities	Outils et niveaux réellement exposés par ce déploiement. Interroge ce point de terminaison en premier.

Rendu et documents

Méthode	Chemin	Objectif
POST	/api/v1/render	Restituer un document à partir d’une liste ordonnée d’opérations et renvoyer le PDF.
POST	/api/v1/extract-text	Extraire le contenu texte d’un PDF.
POST	/api/v1/merge	Fusionner plusieurs entrées PDF en un seul document.
POST	/api/v1/split	Découper un PDF en plusieurs documents.

Jobs asynchrones

Méthode	Chemin	Objectif
POST	/api/v1/jobs	Soumettre une opération de longue durée sous forme de job.
GET	/api/v1/jobs/{id}	Interroger l’état du job.
GET	/api/v1/jobs/{id}/result	Récupérer le résultat du job terminé.

Sessions

Les sessions maintiennent un document ouvert sur plusieurs appels, ce qui te permet de le construire progressivement et de ne le restituer qu’une seule fois à la fin.

Méthode	Chemin	Objectif
POST	/api/v1/sessions	Ouvrir une session.
GET / DELETE	/api/v1/sessions/{sessionId}	Inspecter ou fermer une session.
POST	/api/v1/sessions/{sessionId}/pages	Ajouter une page.
POST	/api/v1/sessions/{sessionId}/text	Ajouter du texte.
POST	/api/v1/sessions/{sessionId}/images	Ajouter une image.
POST	/api/v1/sessions/{sessionId}/tables	Ajouter un tableau.
POST	/api/v1/sessions/{sessionId}/html	Ajouter du HTML rendu.
POST	/api/v1/sessions/{sessionId}/font	Définir la police active.
POST	/api/v1/sessions/{sessionId}/render	Restituer le document de la session.

Opérations des éditions commerciales

Ces routes ne sont enregistrées que lorsque l’édition commerciale correspondante est installée. Plusieurs d’entre elles sont soumises à approbation via le flux de confirmation human-in-the-loop ; consulte les niveaux de risque.

Méthode	Chemin	Objectif
POST	/api/v1/sign	Appliquer une signature numérique.
POST	/api/v1/fill-form	Remplir un formulaire interactif.
POST	/api/v1/redact	Caviarder du contenu.
POST	/api/v1/compare	Comparer deux documents PDF.
POST	/api/v1/check-accessibility	Lancer une vérification d’accessibilité structurelle.
POST	/api/v1/optimize	Optimiser et réduire un document.

Modèle d’erreur

Le transport REST utilise les codes d’état HTTP selon la sémantique définie par RFC 9110 : 2xx pour un succès, 4xx pour une requête que l’appelant doit corriger (400 pour un corps mal formé, 401 pour un jeton manquant ou invalide, 403 pour un refus de niveau ou d’approbation, 404 pour une route ou un job inconnu, 409 pour un conflit d’idempotence, 422 pour une requête bien formée que le moteur ne peut pas traiter), et 5xx pour une défaillance côté serveur. Une réponse 401 inclut un défi WWW-Authenticate.

Les corps d’erreur sont des documents application/problem+json conformes à RFC 9457 (Problem Details for HTTP APIs) : un type stable, un title court, le status numérique et un detail lisible par un humain. Utilise le type pour faire la correspondance, pas la chaîne detail. Consulte aussi RFC 9110 (HTTP Semantics) et RFC 9457 pour les définitions normatives.

Soumets les requêtes qui modifient l’état avec un en-tête Idempotency-Key pour qu’une requête réessayée ne soit traitée qu’une seule fois.

Spécification lisible par machine

Le contrat complet est publié sous la forme d’un document OpenAPI 3.1 statique :

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

Utilise-le comme source unique de vérité pour la surface REST :

1. Ouvre l’explorateur d’API interactif, une référence Scalar auto-hébergée dans le navigateur et générée à partir de ce contrat, pour lire et essayer chaque opération avec ses schémas de requête et de réponse.
2. Importe-le dans un client de requêtes tel que Postman ou Insomnia.
3. Génère un client typé pour ton langage avec un générateur OpenAPI.

Le document est un contrat statique, dont la version est fixée à celle du package. Il n’est pas servi par un point de terminaison actif ; il reste donc stable d’un déploiement à l’autre.

Voir aussi

• Référence de l’API Connect — le catalogue d’outils complet sur MCP, REST et gRPC.
• Guide du transport REST — pipeline RoadRunner, authentification par jeton porteur et routage par niveau.
• Présentation de NextPDF Connect — ce qu’est le serveur et comment l’exécuter.