NextPDF Connect — transport REST

Tổng quan nhanh

Transport REST (Representational State Transfer) chạy bin/nextpdf-server trong nhóm worker Hypertext Transfer Protocol (HTTP) của RoadRunner. Một tài liệu OpenAPI 3.1 định nghĩa bề mặt này. Transport này xác thực mọi yêu cầu không phải kiểm tra tình trạng bằng khóa bearer application programming interface (API), đồng thời giới hạn các tuyến đường Pro và Enterprise theo bậc đã cài đặt.

Cài đặt

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

Tổng quan khái niệm

Mỗi yêu cầu đi qua một pipeline middleware PHP Standard Recommendation 15 (PSR-15) trước khi đến handler: gán request-id, giới hạn body-size và tier-payload, Cross-Origin Resource Sharing (CORS), xác thực, ủy quyền capability, giới hạn tốc độ theo từng IP và từng client, tính lũy đẳng và thời gian chờ. Middleware PSR-15 không thể tự tạo phản hồi sẽ ủy thác cho request handler được cung cấp (PSR-15 §2.2 MiddlewareInterface::process, điều khoản psr_15_handlers#2.2.p14). Các đối tượng request PHP Standard Recommendation 7 (PSR-7) trong pipeline là bất biến: lệnh gọi làm thay đổi trạng thái sẽ trả về một instance mới thay vì biến đổi đối tượng gốc (PSR-7 §3.2.1).

Bảng tuyến đường được dựng khi khởi động và phụ thuộc vào runtime. Các tuyến đường Core luôn được đăng ký. Các tuyến đường thao tác Pro chỉ được đăng ký khi Pro hoặc Enterprise đã được cài đặt. Các tuyến đường Enterprise chỉ được đăng ký khi Enterprise đã được cài đặt. Các tuyến đường session chỉ được đăng ký khi session được bật.

Bề mặt API

Các tuyến đường luôn được đăng ký

Phương thức	Đường dẫn	Xác thực
GET	/healthz	không có (liveness)
GET	/readyz	không có (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

Các probe kiểm tra tình trạng là endpoint an toàn, chỉ đọc. Chúng không gây thay đổi trạng thái; đây là thuộc tính của phương thức an toàn được Request for Comments (RFC) 9110 định nghĩa (RFC 9110 §9.2.1).

Các tuyến đường giới hạn theo bậc (phụ thuộc vào runtime)

NextPDF chỉ đăng ký các tuyến đường này khi gói tương ứng đã được cài đặt:

• Đã cài đặt Pro hoặc Enterprise: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
• Đã cài đặt Enterprise: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

Nếu bậc của tuyến đường chưa được cài đặt, tuyến đường đó sẽ không được đăng ký và yêu cầu không được định tuyến. Nếu khóa hợp lệ nhưng bậc của khóa thấp hơn bậc của tuyến đường, yêu cầu bị từ chối với 403. Ở những nơi phơi bày tính năng ký, NextPDF Connect với Pro chỉ cung cấp tính năng ký PDF Advanced Electronic Signatures (PAdES) baseline-B (B-B); các profile xác thực dài hạn không nằm trong bề mặt của transport này.

Hợp đồng OpenAPI

Bề mặt REST được phân phối dưới dạng tài liệu OpenAPI 3.1 tĩnh tại openapi/nextpdf-connect.yaml trong gói. Tài liệu này dùng security scheme khóa API bearer trong header Authorization (Bearer npk_live_{kid}_{secret}). Các phản hồi lỗi dùng tài liệu problem-details RFC 7807 với một URL type cho mỗi điều kiện.

Kết xuất OpenAPI — Scalar

Theo kế hoạch nền tảng tài liệu §12, trang tài liệu tổng hợp kết xuất tài liệu OpenAPI này bằng Scalar (@scalar/api-reference). Trang tích hợp REST nhúng tài liệu đó dưới dạng component <ScalarApiReference src=…>. Tệp openapi/nextpdf-connect.yaml của gói vẫn là nguồn chân lý. Quá trình build trang web kéo về và kết xuất tệp đó, thay vì duy trì thủ công một tài liệu tham chiếu endpoint song song. Không có endpoint phục vụ OpenAPI lúc chạy nào là một phần của server; tài liệu này là một artifact lúc build.

Mẫu mã — Khởi đầu nhanh

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

Mẫu mã — Sản xuất

Chạy profile kết hợp để các transport REST và gRPC cùng dùng chung một supervisor:

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

Trường hợp đặc biệt và những điều cần lưu ý

• Một tuyến đường theo bậc trả về 404 khi gói vắng mặt. Tuyến đường không được đăng ký, nên bộ định tuyến không khớp được với nó. Đây là hành vi nằm trong dự kiến; không phải lỗi xác thực.

• 401 so với 403. 401 nghĩa là yêu cầu không có khóa hợp lệ, và phản hồi mang theo header WWW-Authenticate: Bearer theo RFC 9110 §11.6.1. 403 nghĩa là khóa hợp lệ, nhưng bậc của khóa không được phép thực hiện thao tác đó.

• Session bị tắt theo mặc định. Các tuyến đường /api/v1/sessions/... chỉ tồn tại khi NEXTPDF_SESSIONS_ENABLED=true và các tool khả dụng.

• Các thao tác rủi ro cao vẫn bị kiểm soát. Lệnh gọi REST điều khiển một tool ApprovalRequired sẽ đi qua cùng cổng human-in-the-loop như Model Context Protocol (MCP). Xem /connect/hitl-risk-tiers/.

Hiệu năng

Mỗi worker RoadRunner xử lý một yêu cầu tại một thời điểm. Các lần kết xuất đồng bộ kéo dài sẽ chiếm giữ một worker. Hãy dùng các tuyến đường job bất đồng bộ cho công việc chậm để giải phóng worker. Hãy định cỡ nhóm worker theo độ trễ quan sát được; xem /connect/production-usage/.

Lưu ý về bảo mật

Hãy chấm dứt Transport Layer Security (TLS) ở phía trước listener REST. Theo thiết kế, listener gắn với HTTP văn bản thô và mong đợi một bộ chấm dứt ở phía upstream. Hãy xác thực bằng khóa npk_live_ đủ ngẫu nhiên, lưu trữ khóa bên ngoài hệ thống quản lý mã nguồn, và ưu tiên kho khóa dạng tệp có nạp lại nóng. Xem /connect/security-and-operations/.

Tuân thủ

Tuyên bố	Nguồn	reference_id
401 PHẢI mang theo một WWW-Authenticate thử thách	RFC 9110 §11.6.1
Các phương thức an toàn chỉ đọc	RFC 9110 §9.2.1
Các request PSR-7 là bất biến	PSR-7 §3.2.1
Middleware không thể tạo phản hồi sẽ ủy thác cho request handler được cung cấp	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Bối cảnh thương mại

Các tuyến đường ký, biên tập che, so sánh, trợ năng, tối ưu hóa và tuân thủ chỉ xuất hiện khi nextpdf/premium được cài đặt. Mô hình xác thực không thay đổi; bậc của khóa sẽ quyết định quyền truy cập.

Xem thêm

• /connect/quickstart/ — yêu cầu kết xuất có thể chạy được
• /connect/security-and-operations/ — xác thực và cấu hình TLS
• /connect/production-usage/ — job, tính lũy đẳng, giới hạn tốc độ
• /transports/mcp/ · /transports/grpc/ — các transport khác
• /connect/tool-catalog/ — cách tập tuyến đường ánh xạ vào danh mục tool