NextPDF Connect — REST 傳輸

概覽

REST 傳輸會在 RoadRunner HTTP worker 池中執行 bin/nextpdf-server。它由一份 OpenAPI 3.1 文件描述，會使用 bearer API 金鑰驗證每個非健康檢查請求，並依已安裝的方案分級管制 Pro 與 Enterprise 路由。

安裝

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

概念總覽

每個請求在抵達 handler 之前，都會先流經一條 PSR-15 middleware（中介層）管線：指派 request-id、限制 body 大小與方案級的 payload、CORS、驗證、能力授權、逐 IP 與逐用戶端的速率限制、冪等性，以及逾時。無法自行產生回應的 PSR-15 middleware，會委派給所提供的 request handler（PSR-15 §2.2 MiddlewareInterface::process，條號 psr_15_handlers#2.2.p14）；管線傳遞的 PSR-7 請求物件是不可變的——會變更狀態的呼叫會回傳新的實例，而不是就地修改（PSR-7 §3.2.1）。

路由表會在啟動時建立，且取決於執行階段狀態：核心路由一律註冊；Pro 操作路由只會在安裝 Pro 或 Enterprise 時註冊；Enterprise 路由只會在安裝 Enterprise 時註冊。Session 路由只會在啟用 session 時註冊。

API 介面

一律註冊的路由

方法	路徑	驗證
GET	/healthz	無（liveness 存活檢查）
GET	/readyz	無（readiness 就緒檢查）
POST	/api/v1/render	bearer（持有者權杖）
GET	/api/v1/capabilities	持有者權杖
POST	/api/v1/jobs	持有者權杖
GET	/api/v1/jobs/{id}	持有者權杖
GET	/api/v1/jobs/{id}/result	持有者權杖
DELETE	/api/v1/jobs/{id}	持有者權杖
POST	/api/v1/extract-text · /merge · /split	持有者權杖

健康檢查探針是安全的唯讀端點——它們不會造成任何狀態變更，這正符合 RFC 9110 對安全方法的定義（RFC 9110 §9.2.1）。

依方案分級的路由（與執行階段狀態相依）

只有安裝對應套件時才會註冊：

• 安裝 Pro 或 Enterprise： /api/v1/sign、/fill-form、/redact、/compare、/check-accessibility、/optimize。
• 安裝 Enterprise： /api/v1/compliance-check、/forensic-analyze、/ai-certify。

向某個尚未安裝方案分級的路由發出的請求，不會被路由。使用低於該路由所需方案分級的金鑰進行驗證時，請求會以 403 遭到拒絕。在開放簽章的情況下，搭配 Pro 的 NextPDF Connect 僅提供 PAdES baseline-B（B-B）簽章；長期驗證設定檔不屬於此傳輸的介面範圍。

OpenAPI 合約

REST 介面隨套件附帶一份靜態 OpenAPI 3.1 文件，位於 openapi/nextpdf-connect.yaml。它的安全機制是放在 Authorization 標頭中的 bearer API 金鑰（Bearer npk_live_{kid}_{secret}）。錯誤回應是 RFC 7807 problem-details 文件，每種狀況各帶一個 type URL。

OpenAPI 算繪 — Scalar

依文件平台計畫 §12，經 aggregate（聚合）的文件網站會以 Scalar 算繪這份 OpenAPI 文件（@scalar/api-reference）。它以 <ScalarApiReference src=…> 元件的形式嵌入在 REST 整合頁面上。事實來源是套件的 openapi/nextpdf-connect.yaml。網站建構會拉取並算繪它，而不是手動維護一份平行的端點參考文件。伺服器不包含可在執行階段供應 OpenAPI 的端點；該文件是建構階段的產物。

程式碼範例 — 快速開始

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

程式碼範例 — 正式環境

使用合併設定檔，讓 REST 與 gRPC 傳輸共用同一個 supervisor：

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

邊角案例與注意事項

• 當套件未安裝時，方案分級路由會回傳 404。 該路由並未註冊，因此路由器不會比對到它。這是預期行為；它並非驗證失敗。

• 401 與 403 的差別。 401 代表沒有有效金鑰（回應會包含 WWW-Authenticate: Bearer 標頭，依 RFC 9110 §11.6.1）。403 代表金鑰有效，但其方案分級無權使用該操作。

• Session 預設為關閉。 /api/v1/sessions/... 路由只有在 NEXTPDF_SESSIONS_ENABLED=true 且工具可用時才會存在。

• 高風險操作仍會受到管制。 驅動 ApprovalRequired 工具的 REST 呼叫，會經過與 MCP 相同的 human-in-the-loop（人為審核）關卡。請參閱 /connect/hitl-risk-tiers/。

效能

每個 RoadRunner worker 一次只處理一個請求。長時間的同步算繪會占用一個 worker；對於緩慢的工作，請改用非同步 job 路由，讓 worker 得以釋放。請依觀察到的延遲調整 worker 池大小；請參閱 /connect/production-usage/。

安全注意事項

請在 REST 監聽器前端終止 TLS；它在設計上綁定明文 HTTP，並預期前端有一個 TLS 終止點。請使用一組足夠隨機的 npk_live_ 金鑰進行驗證，將金鑰存放在版本控制之外，並優先採用可熱重載的檔案金鑰儲存區。請參閱 /connect/security-and-operations/。

符合性

主張	來源	reference_id
401 必須帶有 WWW-Authenticate 質詢	RFC 9110 §11.6.1
安全方法為唯讀	RFC 9110 §9.2.1
PSR-7 請求是不可變的	PSR-7 §3.2.1
無法產生回應的 middleware 會委派給所提供的 request handler	PSR-15 §2.2 MiddlewareInterface::process（psr_15_handlers#2.2.p14）

商業情境

簽章、redaction（編修）、比對、無障礙、最佳化與符合性路由，只有在安裝 nextpdf/premium 時才會出現。驗證模型維持不變；存取權限由金鑰的方案分級決定。

另請參閱

• /connect/quickstart/ — 可實際執行的算繪請求
• /connect/security-and-operations/ — 驗證與 TLS 配置
• /connect/production-usage/ — job、冪等性、速率限制
• /transports/mcp/ · /transports/grpc/ — 其他傳輸
• /connect/tool-catalog/ — 路由集合如何對映到工具目錄