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/ — 路由集合如何映射到工具目录