NextPDF Connect — transport REST

W skrócie

Transport Representational State Transfer (REST) uruchamia bin/nextpdf-server w puli procesów roboczych RoadRunner dla Hypertext Transfer Protocol (HTTP). Dokument OpenAPI 3.1 definiuje powierzchnię API tego transportu. Transport uwierzytelnia każde żądanie poza sondami kondycji za pomocą klucza API typu bearer i bramkuje trasy Pro oraz Enterprise według zainstalowanego poziomu licencji.

Instalacja

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

Przegląd koncepcyjny

Każde żądanie, zanim trafi do procedury obsługi, przechodzi przez potok oprogramowania pośredniczącego PHP Standard Recommendation 15 (PSR-15). Potok obejmuje przypisanie identyfikatora żądania, limity rozmiaru treści i ładunku zależne od poziomu licencji, Cross-Origin Resource Sharing (CORS), uwierzytelnianie, autoryzację uprawnień, ograniczanie liczby żądań na adres IP oraz na klienta, idempotentność i limit czasu. Oprogramowanie pośredniczące PSR-15, które nie może samodzielnie wytworzyć odpowiedzi, deleguje obsługę do dostarczonej procedury obsługi żądania (PSR-15 §2.2 MiddlewareInterface::process, klauzula psr_15_handlers#2.2.p14). Obiekty żądań PHP Standard Recommendation 7 (PSR-7) w potoku są niezmienne: metoda zmieniająca stan zwraca nową instancję, zamiast modyfikować oryginał (PSR-7 §3.2.1).

Tablica tras jest budowana podczas rozruchu i zależy od środowiska uruchomieniowego. Trasy Core są rejestrowane zawsze. Trasy operacji Pro są rejestrowane tylko wtedy, gdy zainstalowano Pro lub Enterprise. Trasy Enterprise są rejestrowane tylko wtedy, gdy zainstalowano Enterprise. Trasy sesji są rejestrowane tylko wtedy, gdy sesje są włączone.

Powierzchnia API

Trasy rejestrowane zawsze

Metoda	Ścieżka	Uwierzytelnianie
GET	/healthz	brak (liveness)
GET	/readyz	brak (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

Sondy kondycji to bezpieczne punkty końcowe przeznaczone wyłącznie do odczytu. Nie powodują żadnej zmiany stanu, co odpowiada właściwości metody bezpiecznej zdefiniowanej w Request for Comments (RFC) 9110 (RFC 9110 §9.2.1).

Trasy bramkowane poziomem licencji (zależne od środowiska uruchomieniowego)

NextPDF rejestruje poniższe trasy tylko wtedy, gdy zainstalowano odpowiedni pakiet:

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

Jeśli poziom licencji wymagany przez trasę nie jest zainstalowany, trasa nie jest rejestrowana, a żądanie nie jest kierowane do obsługi. Jeśli klucz jest prawidłowy, lecz jego poziom licencji jest niższy niż poziom wymagany przez trasę, żądanie jest odrzucane z kodem 403. Tam, gdzie podpisywanie jest dostępne, NextPDF Connect z Pro zapewnia wyłącznie podpisywanie PDF Advanced Electronic Signatures (PAdES) baseline-B (B-B); profile długoterminowej walidacji nie są częścią powierzchni tego transportu.

Kontrakt OpenAPI

Powierzchnia REST jest udostępniana jako statyczny dokument OpenAPI 3.1 pod ścieżką openapi/nextpdf-connect.yaml w pakiecie. Wykorzystuje schemat zabezpieczeń oparty na kluczu API typu bearer w nagłówku Authorization (Bearer npk_live_{kid}_{secret}). Odpowiedzi błędów wykorzystują dokumenty problem-details zgodne z RFC 7807, z adresem URL w polu type dla każdego przypadku.

Renderowanie OpenAPI — Scalar

Zgodnie z planem platformy dokumentacji §12 zagregowana witryna dokumentacji renderuje ten dokument OpenAPI za pomocą narzędzia Scalar (@scalar/api-reference). Strona integracji REST osadza dokument jako komponent <ScalarApiReference src=…>. Plik openapi/nextpdf-connect.yaml w pakiecie pozostaje jedynym źródłem prawdy. Proces budowania witryny pobiera ten plik i renderuje go, zamiast ręcznie utrzymywać równoległą dokumentację punktów końcowych. Serwer nie zawiera żadnego punktu końcowego udostępniającego OpenAPI w czasie działania; dokument jest artefaktem powstającym podczas budowania.

Przykład kodu — szybki start

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

Przykład kodu — produkcja

Uruchom połączony profil, aby transporty REST i gRPC korzystały z jednego nadzorcy:

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

Przypadki brzegowe i pułapki

• Trasa bramkowana poziomem licencji zwraca 404, gdy pakiet jest nieobecny. Trasa nie jest zarejestrowana, więc router jej nie dopasowuje. To zachowanie oczekiwane; nie oznacza niepowodzenia uwierzytelniania.

• 401 a 403. 401 oznacza, że żądanie nie zawiera prawidłowego klucza, a odpowiedź zawiera nagłówek WWW-Authenticate: Bearer zgodnie z RFC 9110 §11.6.1. 403 oznacza, że klucz jest prawidłowy, lecz jego poziom licencji nie uprawnia do tej operacji.

• Sesje są domyślnie wyłączone. Trasy /api/v1/sessions/... istnieją tylko wtedy, gdy ustawiono NEXTPDF_SESSIONS_ENABLED=true i narzędzia są dostępne.

• Operacje wysokiego ryzyka nadal podlegają bramkowaniu. Wywołanie REST, które uruchamia narzędzie ApprovalRequired, przechodzi przez tę samą bramkę zatwierdzania przez człowieka, co Model Context Protocol (MCP). Zobacz /connect/hitl-risk-tiers/.

Wydajność

Każdy proces roboczy RoadRunner obsługuje naraz jedno żądanie. Długie renderowania synchroniczne zajmują proces roboczy. W przypadku powolnych zadań korzystaj z asynchronicznych tras zadań, aby zwalniać procesy robocze. Dobierz rozmiar puli na podstawie obserwowanych opóźnień; zobacz /connect/production-usage/.

Uwagi dotyczące bezpieczeństwa

Terminuj Transport Layer Security (TLS) przed listenerem REST. Listener z założenia nasłuchuje przez HTTP w postaci jawnej i oczekuje terminacji TLS po stronie nadrzędnej. Używaj do uwierzytelniania dostatecznie losowego klucza npk_live_, przechowuj klucze poza systemem kontroli wersji i preferuj plikowy magazyn kluczy z przeładowaniem na gorąco. Zobacz /connect/security-and-operations/.

Zgodność

Stwierdzenie	Źródło	reference_id
401 MUSI zawierać wyzwanie WWW-Authenticate	RFC 9110 §11.6.1
Metody bezpieczne są tylko do odczytu	RFC 9110 §9.2.1
Żądania PSR-7 są niezmienne	PSR-7 §3.2.1
Oprogramowanie pośredniczące, które nie może wytworzyć odpowiedzi, deleguje obsługę do dostarczonej procedury obsługi żądania	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Kontekst komercyjny

Trasy podpisywania, redagowania, porównywania, sprawdzania dostępności, optymalizacji i kontroli zgodności są rejestrowane tylko wtedy, gdy zainstalowano nextpdf/premium. Model uwierzytelniania pozostaje niezmieniony; o dostępie decyduje poziom licencji klucza.

Zobacz też

• /connect/quickstart/ — działający przykład żądania renderowania
• /connect/security-and-operations/ — uwierzytelnianie i konfiguracja TLS
• /connect/production-usage/ — zadania, idempotentność, ograniczanie liczby żądań
• /transports/mcp/ · /transports/grpc/ — pozostałe transporty
• /connect/tool-catalog/ — jak zestaw tras odwzorowuje się na katalog narzędzi