Connect REST API başvuru belgesi

Bir bakışta

NextPDF Connect, araç kaydını HTTP üzerinden REST taşıması olarak sunar; bu yüzey bir OpenAPI 3.1 sözleşmesiyle tanımlanır. Bu sayfa, söz konusu yüzeyin başvuru belgesidir: temel URL, kimlik doğrulamanın nasıl yapılacağı, işlem grupları ve hata modeli. Tam ve makine tarafından okunabilir belirtim yayımlanmıştır; böylece hiçbir şeyi elle kopyalamadan etkileşimli bir gezgine, istemci üretecine veya istek istemcisine yükleyebilirsiniz.

Taşımadan bağımsız araç kataloğu için (REST’in yanı sıra Model Context Protocol ve gRPC üzerindeki aynı işlemler) Connect API başvurusuna bakın. RoadRunner ardışık düzeni, dağıtım ve kimlik doğrulama kurulumu hakkında bilgi için REST taşıma kılavuzuna bakın.

Temel URL ve kimlik doğrulama

REST taşıması, dağıtımınız için yapılandırılan ana makine ve bağlantı noktasında dinler. Yerel çalıştırmada bu adres http://localhost:8080 olur; üretimde ise işçi havuzunuzun önündeki adrestir.

Kimlik doğrulama, taşıyıcı belirteç tabanlıdır. API anahtarını, katman korumalı bir yola yapılan her istekte Authorization başlığında gönderin:

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

Canlılık ve hazırlık yoklamaları salt okunurdur ve belirteç gerektirmez.

İşlemler

Kullanılabilirlik katmana göre korunur. Açık kaynaklı çekirdek belge, işleme, oturum ve iş işlemlerini içerir. İmzalama, form doldurma, sansürleme, karşılaştırma, erişilebilirlik denetimi ve iyileştirme, sunucuyla birlikte kurulmuş ticari bir sürüm gerektirir. Belirli bir dağıtım için yetkilendirilmiş küme, yetenekler uç noktası tarafından döndürülür. Sabit bir liste varsaymak yerine bu uç noktayı sorgulayın.

Sağlık ve yaşam döngüsü

Yöntem	Yol	Amaç
GET	/healthz	Canlılık yoklaması. Kimlik doğrulama gerekmez.
GET	/readyz	Hazırlık yoklaması (bağımlılıklar ve işçi havuzu hazır). Kimlik doğrulama gerekmez.
GET	/api/v1/capabilities	Bu dağıtımın fiilen sunduğu araçlar ve katmanlar. Önce bunu sorgulayın.

İşleme ve belgeler

Yöntem	Yol	Amaç
POST	/api/v1/render	Sıralı bir işlem listesinden bir belge işler ve PDF’yi döndürür.
POST	/api/v1/extract-text	Bir PDF’den metin içeriğini çıkarır.
POST	/api/v1/merge	Birkaç PDF girdisini tek bir belgede birleştirir.
POST	/api/v1/split	Bir PDF’yi birden çok belgeye böler.

Eşzamansız işler

Yöntem	Yol	Amaç
POST	/api/v1/jobs	Uzun süren bir işlemi iş olarak gönderir.
GET	/api/v1/jobs/{id}	İş durumunu yoklar.
GET	/api/v1/jobs/{id}/result	Tamamlanan iş sonucunu alır.

Oturumlar

Oturumlar, bir belgeyi birden çok çağrı boyunca açık tutar; böylece belgeyi artımlı olarak oluşturur ve sonunda bir kez işlersiniz.

Yöntem	Yol	Amaç
POST	/api/v1/sessions	Bir oturum açar.
GET / DELETE	/api/v1/sessions/{sessionId}	Bir oturumu inceler veya kapatır.
POST	/api/v1/sessions/{sessionId}/pages	Bir sayfa ekler.
POST	/api/v1/sessions/{sessionId}/text	Metin ekler.
POST	/api/v1/sessions/{sessionId}/images	Bir görüntü ekler.
POST	/api/v1/sessions/{sessionId}/tables	Bir tablo ekler.
POST	/api/v1/sessions/{sessionId}/html	İşlenmiş HTML ekler.
POST	/api/v1/sessions/{sessionId}/font	Etkin yazı tipini ayarlar.
POST	/api/v1/sessions/{sessionId}/render	Oturum belgesini işler.

Ticari sürüm işlemleri

Bu yollar yalnızca ilgili ticari sürüm kurulduğunda kaydedilir. Bunlardan birkaçı, insanın döngüde olduğu onay akışıyla korunur; risk katmanlarına bakın.

Yöntem	Yol	Amaç
POST	/api/v1/sign	Dijital imza uygular.
POST	/api/v1/fill-form	Etkileşimli bir formu doldurur.
POST	/api/v1/redact	İçeriği sansürler.
POST	/api/v1/compare	İki PDF belgesini karşılaştırır.
POST	/api/v1/check-accessibility	Yapısal bir erişilebilirlik denetimi çalıştırır.
POST	/api/v1/optimize	Bir belgeyi iyileştirir ve küçültür.

Hata modeli

REST taşıması, anlamı RFC 9110 tarafından tanımlanan HTTP durum kodlarını kullanır: başarı için 2xx, çağıranın düzeltmesi gereken istekler için 4xx (400 hatalı biçimlendirilmiş gövde, 401 eksik veya geçersiz belirteç, 403 katman veya onay reddedildi, 404 bilinmeyen yol veya iş, 409 idempotentlik çakışması, 422 motorun işleyemediği iyi biçimlendirilmiş bir istek) ve sunucu tarafındaki başarısızlıklar için 5xx. Bir 401 yanıtı, bir WWW-Authenticate sınaması içerir.

Hata gövdeleri, RFC 9457 (Problem Details for HTTP APIs) uyarınca application/problem+json belgeleridir: kararlı bir type, kısa bir title, sayısal status ve insan tarafından okunabilir bir detail. type alanına göre eşleştirin, detail dizesine göre değil. Normatif tanımlar için ayrıca RFC 9110 (HTTP Semantics) ve RFC 9457 belgelerine bakın.

Durumu değiştiren istekleri bir Idempotency-Key başlığıyla gönderin; böylece tekrar denenen bir istek yalnızca bir kez işlenir.

Makine tarafından okunabilir belirtim

Tam sözleşme, statik bir OpenAPI 3.1 belgesi olarak yayımlanır:

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

Bunu REST yüzeyi için tek doğruluk kaynağı olarak kullanın:

1. Her işlemi, kendi istek ve yanıt şemalarıyla birlikte okumak ve denemek için etkileşimli API gezginini — bu sözleşmeden üretilen, tarayıcı içinde çalışan, kendi kendine barındırılan bir Scalar başvurusu — açın.
2. Bunu Postman veya Insomnia gibi bir istek istemcisine içe aktarın.
3. Bir OpenAPI üreteciyle, kendi diliniz için türlenmiş bir istemci oluşturun.

Belge, sürümü pakete sabitlenmiş statik bir sözleşmedir. Canlı bir uç nokta tarafından sunulmaz; bu nedenle dağıtımlar arasında kararlı kalır.

Ayrıca bakınız

• Connect API başvurusu — MCP, REST ve gRPC üzerindeki tam araç kataloğu.
• REST taşıma kılavuzu — RoadRunner ardışık düzeni, taşıyıcı kimlik doğrulaması ve katman yönlendirme.
• NextPDF Connect genel bakışı — sunucunun ne olduğu ve nasıl çalıştırılacağı.