NextPDF Connect — REST taşıma katmanı

Bir bakışta

Representational State Transfer (REST) taşıma katmanı, bin/nextpdf-server dosyasını bir RoadRunner Hypertext Transfer Protocol (HTTP) çalışan havuzunda çalıştırır. Arayüzünü bir OpenAPI 3.1 belgesi tanımlar. Taşıma katmanı, sağlık denetimleri dışındaki her isteğin kimliğini bir taşıyıcı (bearer) application programming interface (API) anahtarıyla doğrular ve Pro ile Enterprise yollarına erişimi kurulu katmana göre denetler.

Kurulum

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

Kavramsal genel bakış

Her istek, bir işleyiciye ulaşmadan önce bir PHP Standard Recommendation 15 (PSR-15) ara katman işlem hattından geçer: istek kimliği atama, gövde boyutu ve katman yükü sınırları, Cross-Origin Resource Sharing (CORS), kimlik doğrulama, yetenek yetkilendirme, IP başına ve istemci başına hız sınırlaması, eşgüçlülük (idempotency) ve zaman aşımı. Yanıtı kendisi üretemeyen bir PSR-15 ara katmanı, işlemi sağlanan istek işleyicisine devreder (PSR-15 §2.2 MiddlewareInterface::process, madde psr_15_handlers#2.2.p14). İşlem hattındaki PHP Standard Recommendation 7 (PSR-7) istek nesneleri değiştirilemezdir: durumu değiştiren bir çağrı, özgün nesneyi değiştirmek yerine yeni bir örnek döndürür (PSR-7 §3.2.1).

Yol tablosu başlatma sırasında oluşturulur ve çalışma zamanına bağlıdır. Core yolları her zaman kaydedilir. Pro işlem yolları yalnızca Pro veya Enterprise kuruluyken kaydedilir. Enterprise yolları yalnızca Enterprise kuruluyken kaydedilir. Oturum yolları yalnızca oturumlar etkinleştirildiğinde kaydedilir.

API yüzeyi

Her zaman kaydedilen yollar

Yöntem	Yol	Kimlik doğrulama
GET	/healthz	yok (canlılık)
GET	/readyz	yok (hazır olma)
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

Sağlık denetimleri güvenli, salt okunur uç noktalardır. Hiçbir durum değişikliğine yol açmazlar; bu, Request for Comments (RFC) 9110 tarafından tanımlanan güvenli yöntemlerin özelliğidir (RFC 9110 §9.2.1).

Katmana göre erişimi denetlenen yollar (çalışma zamanına bağlı)

NextPDF bu yolları yalnızca ilgili paket kurulu olduğunda kaydeder:

• Pro veya Enterprise kurulu olduğunda: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
• Enterprise kurulu olduğunda: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

Yolun gerektirdiği katman kurulu değilse, yol kaydedilmez ve istek yönlendirilmez. Anahtar geçerli olsa da anahtarın katmanı yolun gerektirdiği katmanın altındaysa, istek 403 ile reddedilir. İmzalama erişime açıldığında NextPDF Connect, Pro ile yalnızca PDF Advanced Electronic Signatures (PAdES) baseline-B (B-B) imzalama sağlar; uzun süreli doğrulama profilleri bu taşıma katmanının arayüzüne dâhil değildir.

OpenAPI sözleşmesi

REST arayüzü, paketteki openapi/nextpdf-connect.yaml konumunda statik bir OpenAPI 3.1 belgesi olarak gönderilir. Authorization başlığında taşıyıcı (bearer) API anahtarı güvenlik şemasını kullanır (Bearer npk_live_{kid}_{secret}). Hata yanıtları, her koşul için bir type URL’si içeren RFC 7807 sorun ayrıntıları belgelerini kullanır.

OpenAPI oluşturma — Scalar

Belge platformu planı §12 uyarınca, toplanmış belge sitesi bu OpenAPI belgesini Scalar ile oluşturur (@scalar/api-reference). REST tümleştirme sayfası, belgeyi bir <ScalarApiReference src=…> bileşeni olarak gömer. Paketin openapi/nextpdf-connect.yaml dosyası, doğruluk kaynağı olmaya devam eder. Site yapısı, paralel bir uç nokta başvurusunu elle güncel tutmak yerine bu dosyayı alır ve oluşturur. Sunucu içinde çalışma zamanında OpenAPI sunan bir uç nokta yoktur; belge, yapı zamanında üretilen bir yapıttır.

Kod örneği — hızlı başlangıç

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

Kod örneği — üretim

REST ve gRPC taşıma katmanlarının aynı denetleyiciyi paylaşması için birleşik profili çalıştırın:

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

Uç durumlar ve dikkat edilecek noktalar

• Paket yokken bir katman yolu 404 döndürür. Yol kaydedilmediğinden yönlendirici bu yolla eşleşmez. Bu beklenen bir durumdur; kimlik doğrulama hatası değildir.

• 401 ile 403 karşılaştırması. 401, isteğin geçerli bir anahtarı olmadığı anlamına gelir ve yanıt, RFC 9110 §11.6.1 uyarınca bir WWW-Authenticate: Bearer başlığı taşır. 403, anahtarın geçerli olduğu ancak katmanının bu işlem için yetkili olmadığı anlamına gelir.

• Oturumlar varsayılan olarak devre dışıdır. /api/v1/sessions/... yolları yalnızca NEXTPDF_SESSIONS_ENABLED=true olduğunda ve araçlar kullanılabilir olduğunda vardır.

• Yüksek riskli işlemler yine de erişim denetiminden geçer. Bir ApprovalRequired aracını yürüten bir REST çağrısı, Model Context Protocol (MCP) ile aynı insanın süreçte olduğu (human-in-the-loop) geçitten geçer. Bkz. /connect/hitl-risk-tiers/.

Performans

Her RoadRunner çalışanı aynı anda bir isteği işler. Uzun süren eşzamanlı oluşturma işlemleri bir çalışanı meşgul tutar. Çalışanların serbest kalması için yavaş işlerde eşzamansız iş yollarını kullanın. Havuzu gözlemlenen gecikmeye göre boyutlandırın; bkz. /connect/production-usage/.

Güvenlik notları

Transport Layer Security (TLS) protokolünü REST dinleyicisinin önünde sonlandırın. Dinleyici, tasarım gereği düz metin HTTP’ye bağlanır ve yukarı akışta bir sonlandırıcı bekler. Yeterli rastgeleliğe sahip bir npk_live_ anahtarıyla kimlik doğrulayın, anahtarları sürüm denetiminin dışında saklayın ve sıcak yeniden yüklemeyi destekleyen dosya anahtar deposunu tercih edin. Bkz. /connect/security-and-operations/.

Uyumluluk

İddia	Kaynak	reference_id
401 bir WWW-Authenticate sınaması taşımalıdır (MUST)	RFC 9110 §11.6.1
Güvenli yöntemler salt okunurdur	RFC 9110 §9.2.1
PSR-7 istekleri değiştirilemezdir	PSR-7 §3.2.1
Yanıtı üretemeyen ara katman, işlemi sağlanan istek işleyicisine devreder	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Ticari bağlam

İmzalama, redaksiyon, karşılaştırma, erişilebilirlik, optimizasyon ve uyumluluk yolları yalnızca nextpdf/premium kuruluyken görünür. Kimlik doğrulama modeli değişmeden kalır; erişimi anahtarın katmanı belirler.

Ayrıca bkz.

• /connect/quickstart/ — çalıştırılabilir oluşturma isteği
• /connect/security-and-operations/ — kimlik doğrulama ve TLS yaklaşımı
• /connect/production-usage/ — işler, eşgüçlülük (idempotency), hız sınırlaması
• /transports/mcp/ · /transports/grpc/ — diğer taşıma katmanları
• /connect/tool-catalog/ — yol kümesinin araç kataloğuna nasıl eşlendiği