Referensi Connect REST API

Sekilas pandang

NextPDF Connect mengekspos registri alatnya melalui HTTP sebagai transport REST yang dijelaskan oleh kontrak OpenAPI 3.1. Halaman ini menjadi referensi untuk antarmuka tersebut: base URL, autentikasi, grup operasi, dan model kesalahan. Spesifikasi lengkap yang dapat dibaca mesin diterbitkan agar Anda dapat memuatnya ke penjelajah interaktif, generator klien, atau klien permintaan tanpa menyalin apa pun secara manual.

Untuk katalog alat yang tidak bergantung pada transport (operasi yang sama melalui Model Context Protocol dan gRPC di samping REST), lihat Referensi Connect API. Untuk penyiapan pipeline RoadRunner, deployment, dan autentikasi, lihat Panduan transport REST.

Base URL dan autentikasi

Transport REST mendengarkan di host dan port yang dikonfigurasi untuk deployment Anda. Pada eksekusi lokal, nilainya adalah http://localhost:8080; pada produksi, nilainya adalah alamat di depan worker pool Anda.

Autentikasi menggunakan token bearer. Kirim kunci API melalui header Authorization pada setiap permintaan ke rute yang dibatasi tingkatan:

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"}]}'

Probe liveness dan readiness yang bersifat hanya-baca tidak memerlukan token.

Operasi

Ketersediaan dibatasi berdasarkan tingkatan. Inti open-source menyertakan operasi document, render, session, dan job. Penandatanganan, pengisian formulir, redaksi, perbandingan, pemeriksaan aksesibilitas, dan optimisasi memerlukan edisi komersial yang dipasang bersama server. Kumpulan otoritatif untuk suatu deployment dikembalikan oleh endpoint capabilities. Kueri endpoint tersebut alih-alih mengasumsikan daftar tetap.

Health dan lifecycle

Metode	Path	Tujuan
GET	/healthz	Probe liveness. Tanpa autentikasi.
GET	/readyz	Probe readiness (dependensi dan worker pool siap). Tanpa autentikasi.
GET	/api/v1/capabilities	Alat dan tingkatan yang benar-benar diekspos oleh deployment ini. Kueri endpoint ini terlebih dahulu.

Perenderan dan dokumen

Metode	Path	Tujuan
POST	/api/v1/render	Render dokumen dari daftar operasi yang terurut, lalu kembalikan PDF.
POST	/api/v1/extract-text	Ekstrak konten teks dari PDF.
POST	/api/v1/merge	Gabungkan beberapa input PDF menjadi satu dokumen.
POST	/api/v1/split	Pisahkan PDF menjadi beberapa dokumen.

Job asinkron

Metode	Path	Tujuan
POST	/api/v1/jobs	Kirim operasi berdurasi panjang sebagai job.
GET	/api/v1/jobs/{id}	Pantau status job.
GET	/api/v1/jobs/{id}/result	Ambil hasil job yang telah selesai.

Sesi

Sesi menjaga dokumen tetap terbuka lintas beberapa panggilan sehingga Anda dapat membangunnya secara bertahap dan merendernya sekali di akhir.

Metode	Path	Tujuan
POST	/api/v1/sessions	Buka sesi.
GET / DELETE	/api/v1/sessions/{sessionId}	Periksa atau tutup sesi.
POST	/api/v1/sessions/{sessionId}/pages	Tambahkan halaman.
POST	/api/v1/sessions/{sessionId}/text	Tambahkan teks.
POST	/api/v1/sessions/{sessionId}/images	Tambahkan gambar.
POST	/api/v1/sessions/{sessionId}/tables	Tambahkan tabel.
POST	/api/v1/sessions/{sessionId}/html	Tambahkan HTML yang dirender.
POST	/api/v1/sessions/{sessionId}/font	Atur font yang aktif.
POST	/api/v1/sessions/{sessionId}/render	Render dokumen sesi.

Operasi edisi komersial

Rute ini hanya terdaftar ketika edisi komersial yang sesuai dipasang. Beberapa dibatasi oleh persetujuan dalam alur konfirmasi human-in-the-loop; lihat tingkatan risiko.

Metode	Path	Tujuan
POST	/api/v1/sign	Terapkan tanda tangan digital.
POST	/api/v1/fill-form	Isi formulir interaktif.
POST	/api/v1/redact	Lakukan redaksi konten.
POST	/api/v1/compare	Bandingkan dua dokumen PDF.
POST	/api/v1/check-accessibility	Jalankan pemeriksaan aksesibilitas struktural.
POST	/api/v1/optimize	Optimalkan dan perkecil dokumen.

Model kesalahan

Transport REST menggunakan kode status HTTP dengan semantik yang ditetapkan oleh RFC 9110: 2xx untuk keberhasilan, 4xx untuk permintaan yang harus diperbaiki pemanggil (400 body yang tidak valid bentuknya, 401 token tidak ada atau tidak valid, 403 tingkatan atau persetujuan ditolak, 404 rute atau job tidak dikenal, 409 konflik idempotensi, 422 permintaan yang bentuknya benar tetapi tidak dapat diproses mesin), dan 5xx untuk kegagalan di sisi server. Respons 401 menyertakan challenge WWW-Authenticate.

Body kesalahan berbentuk dokumen application/problem+json sesuai RFC 9457 (Problem Details for HTTP APIs): type yang stabil, title singkat, status numerik, dan detail yang dapat dibaca manusia. Cocokkan berdasarkan type, bukan string detail. Lihat juga RFC 9110 (HTTP Semantics) dan RFC 9457 untuk definisi normatif.

Untuk permintaan yang mengubah keadaan, kirim header Idempotency-Key agar permintaan yang diulang tetap diproses satu kali.

Spesifikasi yang dapat dibaca mesin

Kontrak lengkap diterbitkan sebagai dokumen OpenAPI 3.1 statis:

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

Gunakan dokumen tersebut sebagai satu-satunya sumber kebenaran untuk antarmuka REST:

1. Buka penjelajah API interaktif — referensi Scalar yang di-host sendiri di browser dan dihasilkan dari kontrak ini — untuk membaca dan mencoba setiap operasi beserta skema permintaan dan responsnya.
2. Impor ke klien permintaan seperti Postman atau Insomnia.
3. Hasilkan klien bertipe untuk bahasa Anda dengan generator OpenAPI.

Dokumen ini adalah kontrak statis dengan versi yang dipatok ke paket. Dokumen ini tidak dilayani oleh endpoint live, sehingga tetap stabil di seluruh deployment.

Lihat juga

• Referensi Connect API — katalog alat lengkap lintas MCP, REST, dan gRPC.
• Panduan transport REST — pipeline RoadRunner, autentikasi bearer, dan perutean tingkatan.
• Ikhtisar NextPDF Connect — apa itu server tersebut dan cara menjalankannya.