ข้อมูลอ้างอิง Connect REST API

ภาพรวมโดยย่อ

NextPDF Connect เปิดให้เข้าถึงรีจิสทรีเครื่องมือผ่าน HTTP ในรูปแบบการขนส่งแบบ REST ที่อธิบายด้วยสัญญา OpenAPI 3.1 หน้านี้เป็นข้อมูลอ้างอิงสำหรับพื้นผิวดังกล่าว ได้แก่ base URL วิธีการยืนยันตัวตน กลุ่มการดำเนินการ และโมเดลข้อผิดพลาด ข้อกำหนดฉบับเต็มที่อ่านได้ด้วยเครื่องได้รับการเผยแพร่ไว้แล้ว เพื่อให้โหลดเข้าสู่ตัวสำรวจแบบโต้ตอบ ตัวสร้างไคลเอ็นต์ หรือไคลเอ็นต์ส่งคำขอได้โดยไม่ต้องคัดลอกด้วยตนเอง

สำหรับแคตตาล็อกเครื่องมือที่ไม่ขึ้นกับการขนส่ง (การดำเนินการชุดเดียวกันผ่าน Model Context Protocol และ gRPC รวมถึง REST) โปรดดู ข้อมูลอ้างอิง Connect API สำหรับไปป์ไลน์ RoadRunner การปรับใช้ และการตั้งค่าการยืนยันตัวตน โปรดดู คู่มือการขนส่งแบบ REST

Base URL และการยืนยันตัวตน

การขนส่งแบบ REST รอรับการเชื่อมต่อบนโฮสต์และพอร์ตที่กำหนดค่าไว้สำหรับการปรับใช้ ในการรันแบบโลคัล ค่าดังกล่าวคือ http://localhost:8080 ส่วนในการใช้งานจริงคือที่อยู่ที่อยู่หน้า worker pool

การยืนยันตัวตนใช้ bearer token ให้ส่ง API key ในส่วนหัว Authorization สำหรับทุกคำขอที่ส่งไปยังเส้นทางที่จำกัดตามระดับ:

curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

การตรวจสอบ liveness และ readiness แบบอ่านอย่างเดียวไม่จำเป็นต้องใช้ token

การดำเนินการ

ความพร้อมใช้งานถูกจำกัดตามระดับ คอร์โอเพนซอร์สมาพร้อมกับการดำเนินการ document, render, session และ job ส่วนการลงนาม การกรอกฟอร์ม การปกปิดข้อมูล การเปรียบเทียบ การตรวจสอบการช่วยการเข้าถึง และการเพิ่มประสิทธิภาพ ต้องมีรุ่นเชิงพาณิชย์ที่ติดตั้งควบคู่ไปกับเซิร์ฟเวอร์ ชุดที่เชื่อถือได้สำหรับการปรับใช้แต่ละรายการจะถูกส่งกลับโดยปลายทาง capabilities จึงควรสอบถามปลายทางดังกล่าวแทนการสมมติรายการแบบตายตัว

ความสมบูรณ์และวงจรชีวิต

เมธอด	เส้นทาง	วัตถุประสงค์
GET	/healthz	การตรวจสอบ liveness ไม่มีการยืนยันตัวตน
GET	/readyz	การตรวจสอบ readiness (ดีเพนเดนซีและ worker pool พร้อม) ไม่มีการยืนยันตัวตน
GET	/api/v1/capabilities	เครื่องมือและระดับที่การปรับใช้นี้เปิดให้ใช้งานจริง ควรสอบถามรายการนี้ก่อน

การเรนเดอร์และเอกสาร

เมธอด	เส้นทาง	วัตถุประสงค์
POST	/api/v1/render	เรนเดอร์เอกสารจากรายการการดำเนินการที่เรียงลำดับแล้วและส่งคืน PDF
POST	/api/v1/extract-text	แยกเนื้อหาข้อความออกจาก PDF
POST	/api/v1/merge	ผสานอินพุต PDF หลายไฟล์ให้เป็นเอกสารเดียว
POST	/api/v1/split	แยก PDF ออกเป็นหลายเอกสาร

งานแบบอะซิงโครนัส

เมธอด	เส้นทาง	วัตถุประสงค์
POST	/api/v1/jobs	ส่งการดำเนินการที่ใช้เวลานานเป็นงาน
GET	/api/v1/jobs/{id}	สำรวจสถานะของงาน
GET	/api/v1/jobs/{id}/result	ดึงผลลัพธ์ของงานที่เสร็จสมบูรณ์

เซสชัน

เซสชันจะเปิดเอกสารค้างไว้ตลอดการเรียกหลายครั้ง เพื่อให้สร้างเอกสารทีละส่วนแล้วเรนเดอร์เพียงครั้งเดียวในตอนท้าย

เมธอด	เส้นทาง	วัตถุประสงค์
POST	/api/v1/sessions	เปิดเซสชัน
GET / DELETE	/api/v1/sessions/{sessionId}	ตรวจสอบหรือปิดเซสชัน
POST	/api/v1/sessions/{sessionId}/pages	เพิ่มหน้า
POST	/api/v1/sessions/{sessionId}/text	เพิ่มข้อความ
POST	/api/v1/sessions/{sessionId}/images	เพิ่มรูปภาพ
POST	/api/v1/sessions/{sessionId}/tables	เพิ่มตาราง
POST	/api/v1/sessions/{sessionId}/html	เพิ่ม HTML ที่เรนเดอร์แล้ว
POST	/api/v1/sessions/{sessionId}/font	ตั้งค่าฟอนต์ที่ใช้งานอยู่
POST	/api/v1/sessions/{sessionId}/render	เรนเดอร์เอกสารของเซสชัน

การดำเนินการของรุ่นเชิงพาณิชย์

เส้นทางเหล่านี้จะลงทะเบียนเฉพาะเมื่อมีการติดตั้งรุ่นเชิงพาณิชย์ที่ตรงกันเท่านั้น หลายรายการถูกจำกัดด้วยการอนุมัติผ่านโฟลว์การยืนยันแบบ human-in-the-loop โปรดดู ระดับความเสี่ยง

เมธอด	เส้นทาง	วัตถุประสงค์
POST	/api/v1/sign	ใช้ลายเซ็นดิจิทัล
POST	/api/v1/fill-form	กรอกฟอร์มแบบโต้ตอบ
POST	/api/v1/redact	ปกปิดเนื้อหา
POST	/api/v1/compare	เปรียบเทียบเอกสาร PDF สองฉบับ
POST	/api/v1/check-accessibility	เรียกใช้การตรวจสอบการช่วยการเข้าถึงเชิงโครงสร้าง
POST	/api/v1/optimize	เพิ่มประสิทธิภาพและลดขนาดเอกสาร

โมเดลข้อผิดพลาด

การขนส่งแบบ REST ใช้รหัสสถานะ HTTP ตามความหมายที่กำหนดไว้ใน RFC 9110: 2xx สำหรับความสำเร็จ 4xx สำหรับคำขอที่ผู้เรียกต้องแก้ไข (400 เนื้อหาคำขอผิดรูปแบบ 401 ไม่มี token หรือ token ไม่ถูกต้อง 403 ระดับหรือการอนุมัติถูกปฏิเสธ 404 เส้นทางหรืองานที่ไม่รู้จัก 409 ความขัดแย้งด้าน idempotency 422 คำขอถูกต้องตามรูปแบบแต่เอนจินไม่สามารถประมวลผลได้) และ 5xx สำหรับความล้มเหลวฝั่งเซิร์ฟเวอร์ การตอบกลับ 401 จะมาพร้อมคำท้าทาย WWW-Authenticate

เนื้อหาข้อผิดพลาดเป็นเอกสาร application/problem+json ตาม RFC 9457 (Problem Details for HTTP APIs) ได้แก่ type ที่เสถียร title แบบสั้น status ที่เป็นตัวเลข และ detail ที่มนุษย์อ่านได้ ให้จับคู่ตาม type ไม่ใช่ตามสตริง detail ดูเพิ่มเติมที่ RFC 9110 (HTTP Semantics) และ RFC 9457 สำหรับนิยามเชิงบรรทัดฐาน

ส่งคำขอที่เปลี่ยนสถานะพร้อมส่วนหัว Idempotency-Key เพื่อให้คำขอที่ลองใหม่ถูกประมวลผลเพียงครั้งเดียว

ข้อกำหนดที่อ่านได้ด้วยเครื่อง

สัญญาฉบับเต็มเผยแพร่เป็นเอกสาร OpenAPI 3.1 แบบสแตติก:

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

ใช้สัญญานี้เป็นแหล่งข้อมูลจริงเพียงแหล่งเดียวสำหรับพื้นผิว REST:

1. เปิด ตัวสำรวจ API แบบโต้ตอบ ซึ่งเป็นข้อมูลอ้างอิง Scalar แบบโฮสต์เองในเบราว์เซอร์ที่สร้างจากสัญญานี้ เพื่ออ่านและทดลองทุกการดำเนินการพร้อมสคีมาคำขอและการตอบกลับ
2. นำเข้าสัญญานี้สู่ไคลเอ็นต์ส่งคำขอ เช่น Postman หรือ Insomnia
3. สร้างไคลเอ็นต์แบบมีชนิดสำหรับภาษาของคุณด้วยตัวสร้าง OpenAPI

เอกสารนี้เป็นสัญญาแบบสแตติกที่ตรึงเวอร์ชันไว้กับแพ็กเกจ และไม่ได้ให้บริการผ่านปลายทางแบบสด จึงคงเสถียรในทุกการปรับใช้

ดูเพิ่มเติม

• ข้อมูลอ้างอิง Connect API — แคตตาล็อกเครื่องมือฉบับเต็มครอบคลุม MCP, REST และ gRPC
• คู่มือการขนส่งแบบ REST — ไปป์ไลน์ RoadRunner การยืนยันตัวตนแบบ bearer และการกำหนดเส้นทางตามระดับ
• ภาพรวม NextPDF Connect — เซิร์ฟเวอร์นี้คืออะไรและรันอย่างไร