NextPDF Connect — REST-transport

In het kort

Het Representational State Transfer (REST)-transport draait bin/nextpdf-server in een RoadRunner Hypertext Transfer Protocol (HTTP)-workerpool. Een OpenAPI 3.1-document definieert het API-oppervlak. Het transport authenticeert elke niet-health-aanvraag met een bearer application programming interface (API)-sleutel en schermt Pro- en Enterprise-routes af op basis van het geïnstalleerde niveau.

Installeren

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

Conceptueel overzicht

Elke aanvraag passeert een PHP Standard Recommendation 15 (PSR-15)-middlewarepijplijn voordat die een handler bereikt: toewijzing van een request-id, limieten voor body-grootte en payload per niveau, Cross-Origin Resource Sharing (CORS), authenticatie, capability-autorisatie, snelheidsbeperking per IP en per client, idempotentie en een time-out. Een PSR-15-middleware die niet zelf een respons kan produceren, delegeert naar de meegeleverde request-handler (PSR-15 §2.2 MiddlewareInterface::process, clausule psr_15_handlers#2.2.p14). De PHP Standard Recommendation 7 (PSR-7)-request-objecten in de pijplijn zijn immutable: een aanroep die de toestand wijzigt, retourneert een nieuwe instantie in plaats van het origineel te muteren (PSR-7 §3.2.1).

De routetabel wordt bij het opstarten opgebouwd en is afhankelijk van de runtime. Core-routes worden altijd geregistreerd. Pro-bewerkingsroutes worden alleen geregistreerd wanneer Pro of Enterprise is geïnstalleerd. Enterprise-routes worden alleen geregistreerd wanneer Enterprise is geïnstalleerd. Sessieroutes worden alleen geregistreerd wanneer sessies zijn ingeschakeld.

API-oppervlak

Altijd geregistreerde routes

Methode	Pad	Auth
GET	/healthz	geen (liveness)
GET	/readyz	geen (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

De health-probes zijn veilige endpoints die alleen lezen. Ze veroorzaken geen toestandswijziging; dat is de eigenschap van veilige methoden zoals gedefinieerd in Request for Comments (RFC) 9110 (RFC 9110 §9.2.1).

Op niveau afgeschermde routes (runtime-afhankelijk)

NextPDF registreert deze routes alleen wanneer het bijbehorende pakket is geïnstalleerd:

• Pro of Enterprise geïnstalleerd: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
• Enterprise geïnstalleerd: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

Als het niveau dat de route vereist niet is geïnstalleerd, wordt de route niet geregistreerd en wordt de aanvraag niet gerouteerd. Als de sleutel geldig is, maar het niveau ervan lager is dan het niveau van de route, wordt de aanvraag afgewezen met 403. Waar ondertekening beschikbaar is, biedt NextPDF Connect met Pro uitsluitend PDF Advanced Electronic Signatures (PAdES) baseline-B (B-B)-ondertekening; long-term-validation-profielen maken geen deel uit van het oppervlak van dit transport.

OpenAPI-contract

Het REST-oppervlak wordt geleverd als een statisch OpenAPI 3.1-document op openapi/nextpdf-connect.yaml in het pakket. Het gebruikt een beveiligingsschema met bearer-API-sleutel in de Authorization-header (Bearer npk_live_{kid}_{secret}). Foutresponses gebruiken RFC 7807-problem-details-documenten met een type-URL voor elke foutconditie.

OpenAPI-weergave — Scalar

Volgens het documentatieplatformplan §12 geeft de geaggregeerde documentatiesite dit OpenAPI-document weer met Scalar (@scalar/api-reference). De REST-integratiepagina neemt het op als een <ScalarApiReference src=…>-component. De openapi/nextpdf-connect.yaml van het pakket blijft de bron van waarheid. De sitebuild haalt dat bestand op en geeft het weer, in plaats van handmatig een parallelle endpoint-referentie bij te houden. De server bevat geen runtime-endpoint dat OpenAPI aanbiedt; het document is een build-time-artefact.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

Start het gecombineerde profiel, zodat de REST- en gRPC-transports één supervisor delen:

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

Randgevallen en valkuilen

• Een op niveau afgeschermde route retourneert 404 wanneer het pakket ontbreekt. De route wordt niet geregistreerd, dus de router vindt geen overeenkomst. Dit is verwacht gedrag; het is geen authenticatiefout.

• 401 versus 403. 401 betekent dat de aanvraag geen geldige sleutel heeft, en de respons bevat een WWW-Authenticate: Bearer-header conform RFC 9110 §11.6.1. 403 betekent dat de sleutel geldig is, maar dat het niveau ervan geen recht geeft op de bewerking.

• Sessies zijn standaard uitgeschakeld. De /api/v1/sessions/...-routes bestaan alleen wanneer NEXTPDF_SESSIONS_ENABLED=true en tools beschikbaar zijn.

• Bewerkingen met een hoog risico worden nog steeds afgeschermd. Een REST-aanroep die een ApprovalRequired-tool aanstuurt, doorloopt dezelfde human-in-the-loop-gate als het Model Context Protocol (MCP). Zie /connect/hitl-risk-niveaus/.

Prestaties

Elke RoadRunner-worker verwerkt één aanvraag tegelijk. Lange synchrone renderbewerkingen houden een worker bezet. Gebruik de asynchrone job-routes voor langlopende taken, zodat workers worden vrijgegeven. Dimensioneer de pool op basis van de waargenomen latentie; zie /connect/production-usage/.

Beveiligingsnotities

Termineer Transport Layer Security (TLS) vóór de REST-listener. De listener bindt zich bewust aan HTTP in platte tekst en verwacht een upstream-terminator. Authenticeer met een voldoende willekeurige npk_live_-sleutel, bewaar sleutels buiten versiebeheer en geef de voorkeur aan bestandsgebaseerde sleutelopslag met hot-reloading. Zie /connect/security-and-operations/.

Conformiteit

Bewering	Bron	reference_id
401 MOET een WWW-Authenticate-challenge bevatten	RFC 9110 §11.6.1
Veilige methoden zijn alleen-lezen	RFC 9110 §9.2.1
PSR-7-requests zijn immutable	PSR-7 §3.2.1
Middleware die de respons niet kan produceren, delegeert naar de meegeleverde request-handler	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Commerciële context

Routes voor ondertekenen, redigeren, vergelijken, toegankelijkheid, optimaliseren en compliance verschijnen alleen wanneer nextpdf/premium is geïnstalleerd. Het authenticatiemodel blijft ongewijzigd; het niveau van de sleutel bepaalt de toegang.

Zie ook

• /connect/quickstart/ — de uitvoerbare renderaanvraag
• /connect/security-and-operations/ — authenticatie en TLS-inrichting
• /connect/production-usage/ — jobs, idempotentie, snelheidsbeperking
• /transports/mcp/ · /transports/grpc/ — de andere transports
• /connect/tool-catalog/ — hoe de routeset wordt gekoppeld aan de tool-catalogus