NextPDF Connect — transport REST

En bref

Le transport REST exécute bin/nextpdf-server dans un pool de workers HTTP RoadRunner. Il est décrit par un document OpenAPI 3.1, authentifie avec une clé d’API bearer toutes les requêtes sauf les sondes de santé, et contrôle l’accès aux routes Pro et Enterprise en fonction du niveau installé.

Installation

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

Vue d’ensemble conceptuelle

Chaque requête traverse un pipeline de middleware PSR-15 avant d’atteindre un handler : attribution de l’identifiant de requête, limites de taille du corps et de charge utile par niveau, CORS, authentification, autorisation par capacité, limitation de débit par IP et par client, idempotence et délai d’expiration. Un middleware PSR-15 qui ne peut pas produire lui-même la réponse délègue au request handler fourni (PSR-15 §2.2 MiddlewareInterface::process, clause psr_15_handlers#2.2.p14) ; les objets de requête PSR-7 que le pipeline transmet sont immuables — un appel qui modifie l’état renvoie une nouvelle instance au lieu de modifier l’objet en place (PSR-7 §3.2.1).

La table de routage est construite au démarrage et dépend de l’exécution : les routes du cœur sont toujours enregistrées ; les routes d’opération Pro ne le sont que lorsque Pro ou Enterprise est installé ; les routes Enterprise ne le sont que lorsque Enterprise est installé. Les routes de session ne s’enregistrent que lorsque les sessions sont activées.

Surface de l’API

Routes toujours enregistrées

Méthode	Chemin	Authentification
GET	/healthz	aucune (liveness)
GET	/readyz	aucune (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

Les sondes de santé sont des endpoints sûrs et en lecture seule — elles ne provoquent aucun changement d’état, propriété que RFC 9110 associe aux méthodes sûres (RFC 9110 §9.2.1).

Routes contrôlées par le niveau (dépendantes de l’exécution)

Enregistrées uniquement lorsque le package correspondant est installé :

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

Une requête ciblant une route dont le niveau n’est pas installé n’est pas routée. Une requête authentifiée avec une clé dont le niveau est inférieur à celui de la route est rejetée avec un 403. Lorsque la signature est exposée, NextPDF Connect avec Pro fournit uniquement la signature PAdES baseline-B (B-B) ; les profils de validation à long terme ne font pas partie de la surface de ce transport.

Contrat OpenAPI

La surface REST est livrée sous forme de document OpenAPI 3.1 statique dans openapi/nextpdf-connect.yaml, au sein du package. Son schéma de sécurité est une clé d’API bearer dans l’en-tête Authorization (Bearer npk_live_{kid}_{secret}). Les réponses d’erreur sont des documents de détails de problème RFC 7807, avec une URL type par condition.

Rendu OpenAPI — Scalar

Conformément au §12 du plan de la plateforme de documentation, le site agrégé de documentation rend ce document OpenAPI avec Scalar (@scalar/api-reference). Il est intégré sous forme de composant <ScalarApiReference src=…> sur la page d’intégration REST. La source de vérité est le fichier openapi/nextpdf-connect.yaml du package. Le build du site le récupère et le rend, au lieu de maintenir à la main une référence parallèle des endpoints. Le serveur n’expose aucun endpoint de service OpenAPI à l’exécution ; le document est un artefact de build.

Exemple de code — Démarrage rapide

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

Exemple de code — Production

Exécute le profil combiné pour que les transports REST et gRPC partagent un seul superviseur :

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

Cas limites et pièges

• Une route de niveau renvoie un 404 lorsque le package est absent. La route n’est pas enregistrée ; le routeur ne peut donc pas la faire correspondre. C’est attendu ; il ne s’agit pas d’un échec d’authentification.

• 401 ou 403. 401 signifie qu’aucune clé valide n’a été fournie (et la réponse inclut un en-tête WWW-Authenticate: Bearer, conformément à RFC 9110 §11.6.1). 403 signifie qu’une clé valide a été fournie, mais que son niveau n’a pas droit à l’opération.

• Les sessions sont désactivées par défaut. Les routes /api/v1/sessions/... n’existent que lorsque NEXTPDF_SESSIONS_ENABLED=true et que les outils sont disponibles.

• Les opérations à haut risque restent contrôlées. Un appel REST qui pilote un outil ApprovalRequired passe par la même barrière d’approbation humaine que MCP. Voir /connect/hitl-risk-tiers/.

Performance

Chaque worker RoadRunner traite une requête à la fois. Les rendus synchrones de longue durée immobilisent un worker ; utilise les routes de jobs asynchrones pour les travaux lents afin de libérer les workers. Dimensionne le pool en fonction de la latence observée ; voir /connect/production-usage/.

Notes de sécurité

Place la terminaison TLS devant l’écouteur REST ; par conception, il écoute en HTTP clair et attend un terminateur en amont. Authentifie-toi avec une clé npk_live_ suffisamment aléatoire, stocke les clés hors du contrôle de version et privilégie le magasin de clés sur fichier avec rechargement à chaud. Voir /connect/security-and-operations/.

Conformité

Affirmation	Source	reference_id
401 doit inclure un défi WWW-Authenticate dans la réponse	RFC 9110 §11.6.1
Les méthodes sûres sont en lecture seule	RFC 9110 §9.2.1
Les requêtes PSR-7 sont immuables	PSR-7 §3.2.1
Un middleware incapable de produire la réponse délègue au request handler fourni	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Contexte commercial

Les routes de signature, de caviardage, de comparaison, d’accessibilité, d’optimisation et de conformité n’apparaissent que lorsque nextpdf/premium est installé. Le modèle d’authentification reste inchangé ; le niveau de la clé détermine l’accès.

Voir aussi

• /connect/quickstart/ — requête de rendu prête à exécuter
• /connect/security-and-operations/ — authentification et posture TLS
• /connect/production-usage/ — jobs, idempotence, limitation de débit
• /transports/mcp/ · /transports/grpc/ — les autres transports
• /connect/tool-catalog/ — correspondance entre l’ensemble des routes et le catalogue d’outils