NextPDF Connect — Transport REST

Sekilas pandang

Transport Representational State Transfer (REST) menjalankan bin/nextpdf-server di dalam worker pool Hypertext Transfer Protocol (HTTP) RoadRunner. Dokumen OpenAPI 3.1 mendefinisikan permukaan API tersebut. Transport ini mengautentikasi setiap permintaan non-health dengan kunci application programming interface (API) bearer, dan membatasi rute Pro serta Enterprise sesuai tier yang terpasang.

Pemasangan

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

Gambaran konseptual

Setiap permintaan melewati pipeline middleware PHP Standard Recommendation 15 (PSR-15) sebelum mencapai handler: penetapan request-id, batas ukuran body dan payload per tier, Cross-Origin Resource Sharing (CORS), autentikasi, otorisasi kapabilitas, pembatasan laju per IP dan per klien, idempotensi, serta batas waktu. Middleware PSR-15 yang tidak dapat menghasilkan respons sendiri akan mendelegasikan pemrosesan ke request handler yang disediakan (PSR-15 §2.2 MiddlewareInterface::process, klausul psr_15_handlers#2.2.p14). Objek permintaan PHP Standard Recommendation 7 (PSR-7) di dalam pipeline bersifat immutable: pemanggilan yang mengubah state mengembalikan instance baru alih-alih memodifikasi objek aslinya (PSR-7 §3.2.1).

Tabel rute dibangun saat boot dan bergantung pada runtime. Rute Core selalu didaftarkan. Rute operasi Pro hanya didaftarkan ketika Pro atau Enterprise terpasang. Rute Enterprise hanya didaftarkan ketika Enterprise terpasang. Rute sesi hanya didaftarkan ketika sesi diaktifkan.

Permukaan API

Rute yang selalu terdaftar

Metode	Jalur	Auth
GET	/healthz	tidak ada (liveness)
GET	/readyz	tidak ada (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

Probe health adalah endpoint yang aman dan hanya-baca. Probe tersebut tidak mengubah state; ini adalah properti safe-method yang didefinisikan oleh Request for Comments (RFC) 9110 (RFC 9110 §9.2.1).

Rute yang dibatasi berdasarkan tier (bergantung pada runtime)

NextPDF mendaftarkan rute berikut hanya ketika paket yang sesuai terpasang:

• Pro atau Enterprise terpasang: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
• Enterprise terpasang: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

Jika tier untuk rute tersebut tidak terpasang, rute tidak didaftarkan dan permintaan tidak dirutekan. Jika kuncinya valid tetapi tier-nya lebih rendah dari tier rute tersebut, permintaan ditolak dengan 403. Ketika penandatanganan tersedia, NextPDF Connect pada Pro hanya menyediakan penandatanganan PDF Advanced Electronic Signatures (PAdES) baseline-B (B-B); profil long-term-validation bukan bagian dari permukaan transport ini.

Kontrak OpenAPI

Permukaan REST disertakan sebagai dokumen OpenAPI 3.1 statis di openapi/nextpdf-connect.yaml dalam paket. Dokumen ini menggunakan skema keamanan kunci API bearer pada header Authorization (Bearer npk_live_{kid}_{secret}). Respons error menggunakan dokumen problem-details RFC 7807 dengan URL type untuk setiap kondisi.

Perenderan OpenAPI — Scalar

Sesuai dengan rencana platform dokumentasi §12, situs dokumentasi teragregasi merender dokumen OpenAPI ini dengan Scalar (@scalar/api-reference). Halaman integrasi REST menyematkannya sebagai komponen <ScalarApiReference src=…>. openapi/nextpdf-connect.yaml dari paket tersebut tetap menjadi sumber kebenaran. Proses build situs mengambil dan merender berkas tersebut alih-alih memelihara referensi endpoint paralel secara manual. Tidak ada endpoint runtime untuk menyajikan OpenAPI yang menjadi bagian dari server; dokumen tersebut adalah artefak build-time.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Jalankan profil gabungan agar transport REST dan gRPC berbagi supervisor yang sama:

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

Kasus tepi dan hal yang perlu diwaspadai

• Rute tier mengembalikan 404 ketika paket tidak ada. Rute tersebut tidak didaftarkan, sehingga router tidak menemukan kecocokan. Ini sesuai harapan; ini bukan kegagalan autentikasi.

• 401 versus 403. 401 berarti permintaan tidak memiliki kunci yang valid, dan responsnya membawa header WWW-Authenticate: Bearer sesuai RFC 9110 §11.6.1. 403 berarti kunci valid, tetapi tier-nya tidak berhak menjalankan operasi tersebut.

• Sesi dinonaktifkan secara default. Rute /api/v1/sessions/... hanya ada ketika NEXTPDF_SESSIONS_ENABLED=true dan tools tersedia.

• Operasi berisiko tinggi tetap melewati gerbang. Panggilan REST yang menjalankan tool ApprovalRequired tetap melalui gerbang human-in-the-loop yang sama dengan Model Context Protocol (MCP). Lihat /connect/hitl-risk-tiers/.

Performa

Setiap worker RoadRunner menangani satu permintaan pada satu waktu. Perenderan sinkron yang lama akan menahan satu worker. Gunakan rute job asinkron untuk pekerjaan yang lambat agar worker dapat dibebaskan. Sesuaikan ukuran pool dengan latensi yang teramati; lihat /connect/production-usage/.

Catatan keamanan

Terminasikan Transport Layer Security (TLS) di depan listener REST. Listener sengaja mengikat HTTP plaintext dan mengharapkan terminator di hulu. Lakukan autentikasi dengan kunci npk_live_ yang cukup acak, simpan kunci di luar kontrol sumber, dan utamakan key store berbasis berkas dengan hot-reloading. Lihat /connect/security-and-operations/.

Konformansi

Klaim	Sumber	reference_id
401 HARUS membawa tantangan WWW-Authenticate	RFC 9110 §11.6.1
Safe method bersifat hanya-baca	RFC 9110 §9.2.1
Permintaan PSR-7 bersifat immutable	PSR-7 §3.2.1
Middleware yang tidak mampu menghasilkan respons mendelegasikannya ke request handler yang disediakan	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Konteks komersial

Rute penandatanganan, redaksi, perbandingan, aksesibilitas, optimasi, dan kepatuhan hanya muncul ketika nextpdf/premium terpasang. Model autentikasi tetap tidak berubah; tier kunci yang menentukan akses.

Lihat juga

• /connect/quickstart/ — permintaan render yang dapat dijalankan
• /connect/security-and-operations/ — autentikasi dan postur TLS
• /connect/production-usage/ — job, idempotensi, pembatasan laju
• /transports/mcp/ · /transports/grpc/ — transport lainnya
• /connect/tool-catalog/ — cara kumpulan rute dipetakan ke katalog tool