NextPDF Connect — การรับส่ง REST

โดยสรุป

การรับส่งแบบ Representational State Transfer (REST) จะรัน bin/nextpdf-server ในพูลเวิร์กเกอร์ Hypertext Transfer Protocol (HTTP) ของ RoadRunner เอกสาร OpenAPI 3.1 เป็นตัวกำหนดพื้นผิวการใช้งาน การรับส่งนี้จะยืนยันตัวตนทุกคำขอที่ไม่ใช่คำขอตรวจสุขภาพด้วย bearer application programming interface (API) key และกั้นเส้นทาง Pro กับ Enterprise ตามระดับที่ติดตั้งไว้

การติดตั้ง

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

ภาพรวมเชิงแนวคิด

แต่ละคำขอจะผ่านไปป์ไลน์มิดเดิลแวร์ PHP Standard Recommendation 15 (PSR-15) ก่อนถึงตัวจัดการ ได้แก่ การกำหนด request-id การจำกัดขนาด body และ payload ตามระดับ Cross-Origin Resource Sharing (CORS) การยืนยันตัวตน การอนุญาตตามความสามารถ การจำกัดอัตราต่อ IP และต่อไคลเอ็นต์ idempotency และการหมดเวลา มิดเดิลแวร์ PSR-15 ที่ไม่สามารถสร้างการตอบสนองเองได้จะส่งต่อให้ตัวจัดการคำขอที่กำหนดไว้ (PSR-15 §2.2 MiddlewareInterface::process ข้อ psr_15_handlers#2.2.p14) อ็อบเจ็กต์คำขอ PHP Standard Recommendation 7 (PSR-7) ในไปป์ไลน์เป็นแบบเปลี่ยนค่าไม่ได้: การเรียกที่เปลี่ยนสถานะจะคืนอินสแตนซ์ใหม่แทนการแก้ไขตัวเดิม (PSR-7 §3.2.1)

ตารางเส้นทางจะสร้างขึ้นเมื่อเริ่มทำงานและขึ้นอยู่กับรันไทม์ เส้นทาง Core จะลงทะเบียนเสมอ เส้นทางการดำเนินการ Pro จะลงทะเบียนเฉพาะเมื่อติดตั้ง Pro หรือ Enterprise แล้วเท่านั้น เส้นทาง Enterprise จะลงทะเบียนเฉพาะเมื่อติดตั้ง Enterprise แล้วเท่านั้น ส่วนเส้นทางเซสชันจะลงทะเบียนเฉพาะเมื่อเปิดใช้งานเซสชันแล้วเท่านั้น

พื้นผิว API

เส้นทางที่ลงทะเบียนเสมอ

เมท็อด	พาธ	การยืนยันตัวตน
GET	/healthz	ไม่มี (liveness)
GET	/readyz	ไม่มี (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

การตรวจสุขภาพเป็น endpoint ที่ปลอดภัยและอ่านอย่างเดียว การตรวจสุขภาพไม่ก่อให้เกิดการเปลี่ยนแปลงสถานะ ซึ่งเป็นคุณสมบัติของเมท็อดที่ปลอดภัยตามนิยามใน Request for Comments (RFC) 9110 (RFC 9110 §9.2.1)

เส้นทางที่กั้นตามระดับ (ขึ้นกับรันไทม์)

NextPDF จะลงทะเบียนเส้นทางเหล่านี้เฉพาะเมื่อติดตั้งแพ็กเกจที่เกี่ยวข้องแล้วเท่านั้น:

• ติดตั้ง Pro หรือ Enterprise: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize
• ติดตั้ง Enterprise: /api/v1/compliance-check, /forensic-analyze, /ai-certify

หากไม่ได้ติดตั้งระดับที่เส้นทางต้องใช้ เส้นทางนั้นจะไม่ถูกลงทะเบียนและคำขอจะไม่ถูกกำหนดเส้นทาง หากคีย์ถูกต้องแต่ระดับของคีย์ต่ำกว่าระดับของเส้นทาง คำขอจะถูกปฏิเสธด้วย 403 ในจุดที่เปิดให้ใช้การลงลายเซ็น NextPDF Connect ที่มี Pro จะให้บริการเฉพาะการลงลายเซ็นแบบ PDF Advanced Electronic Signatures (PAdES) baseline-B (B-B) เท่านั้น โปรไฟล์ long-term-validation ไม่ได้เป็นส่วนหนึ่งของพื้นผิวการรับส่งนี้

สัญญา OpenAPI

พื้นผิว REST จัดส่งเป็นเอกสาร OpenAPI 3.1 แบบสแตติกที่ openapi/nextpdf-connect.yaml ในแพ็กเกจ เอกสารนี้ใช้สคีมาความปลอดภัยแบบ bearer API key ในเฮดเดอร์ Authorization (Bearer npk_live_{kid}_{secret}) การตอบสนองแบบ error ใช้เอกสาร problem-details ตาม RFC 7807 พร้อม URL type สำหรับแต่ละเงื่อนไข

การเรนเดอร์ OpenAPI — Scalar

ตามแผนแพลตฟอร์มเอกสาร §12 เว็บไซต์เอกสารแบบรวมจะเรนเดอร์เอกสาร OpenAPI นี้ด้วย Scalar (@scalar/api-reference) หน้าการผสานรวม REST จะฝังเอกสารนี้เป็นคอมโพเนนต์ <ScalarApiReference src=…> openapi/nextpdf-connect.yaml ของแพ็กเกจยังคงเป็นแหล่งความจริงที่ถูกต้อง กระบวนการบิลด์ของเว็บไซต์จะดึงและเรนเดอร์ไฟล์นั้น แทนการดูแลรายการ endpoint คู่ขนานด้วยมือ เซิร์ฟเวอร์ไม่มี endpoint สำหรับให้บริการ 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 หมายความว่าคีย์ถูกต้อง แต่ระดับของคีย์ไม่มีสิทธิ์สำหรับการดำเนินการนั้น

• เซสชันปิดอยู่โดยค่าเริ่มต้น เส้นทาง /api/v1/sessions/... จะมีอยู่เฉพาะเมื่อ NEXTPDF_SESSIONS_ENABLED=true และมีเครื่องมือพร้อมใช้งาน

• การดำเนินการที่มีความเสี่ยงสูงยังคงถูกกั้น การเรียก REST ที่ขับเคลื่อนเครื่องมือ ApprovalRequired จะผ่านการกั้นแบบ human-in-the-loop เดียวกันกับ Model Context Protocol (MCP) ดู /connect/hitl-risk-tiers/

ประสิทธิภาพ

เวิร์กเกอร์ RoadRunner แต่ละตัวจัดการคำขอครั้งละหนึ่งรายการ การเรนเดอร์แบบซิงโครนัสที่ใช้เวลานานจะยึดเวิร์กเกอร์ไว้ ใช้เส้นทางงานแบบอะซิงโครนัสสำหรับงานที่ช้าเพื่อให้เวิร์กเกอร์ว่าง กำหนดขนาดพูลโดยเทียบกับเวลาแฝงที่สังเกตได้ ดู /connect/production-usage/

หมายเหตุด้านความปลอดภัย

ยุติ Transport Layer Security (TLS) ที่ด้านหน้าของตัวรับฟัง REST ตัวรับฟังผูกกับ HTTP แบบ plaintext โดยการออกแบบ และคาดหวังตัวยุติที่อยู่ชั้นหน้า ยืนยันตัวตนด้วยคีย์ npk_live_ ที่สุ่มอย่างเพียงพอ เก็บคีย์ไว้นอกการควบคุมซอร์ส และควรใช้ที่เก็บคีย์แบบไฟล์ที่โหลดซ้ำได้ทันที ดู /connect/security-and-operations/

ความสอดคล้อง

ข้อกล่าวอ้าง	แหล่งที่มา	reference_id
401 ต้องแนบ WWW-Authenticate challenge	RFC 9110 §11.6.1
เมท็อดที่ปลอดภัยอ่านอย่างเดียว	RFC 9110 §9.2.1
คำขอ PSR-7 เปลี่ยนค่าไม่ได้	PSR-7 §3.2.1
มิดเดิลแวร์ที่ไม่สามารถสร้างการตอบสนองได้จะส่งต่อให้ตัวจัดการคำขอที่กำหนดไว้	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

บริบทเชิงพาณิชย์

เส้นทางสำหรับการลงลายเซ็น การลบทึบ การเปรียบเทียบ การช่วยการเข้าถึง การเพิ่มประสิทธิภาพ และการตรวจสอบความสอดคล้อง จะปรากฏเฉพาะเมื่อติดตั้ง nextpdf/premium แล้วเท่านั้น รูปแบบการยืนยันตัวตนยังคงไม่เปลี่ยนแปลง ระดับของคีย์เป็นตัวกำหนดสิทธิ์การเข้าถึง

ดูเพิ่มเติม

• /connect/quickstart/ — คำขอเรนเดอร์ที่รันได้จริง
• /connect/security-and-operations/ — การยืนยันตัวตนและท่าทีด้าน TLS
• /connect/production-usage/ — งาน idempotency และการจำกัดอัตรา
• /transports/mcp/ · /transports/grpc/ — การรับส่งอื่นๆ
• /connect/tool-catalog/ — วิธีที่ชุดเส้นทางจับคู่กับแค็ตตาล็อกเครื่องมือ