Dokumentacja REST API Connect

W skrócie

NextPDF Connect udostępnia swój rejestr narzędzi przez HTTP jako transport REST opisany kontraktem OpenAPI 3.1. Ta strona opisuje ten interfejs: bazowy adres URL, sposób uwierzytelniania, grupy operacji oraz model błędów. Opublikowana pełna specyfikacja przeznaczona do odczytu maszynowego pozwala wczytać ją do interaktywnego eksploratora, generatora klientów lub klienta zapytań bez ręcznego kopiowania czegokolwiek.

Niezależny od transportu katalog narzędzi (te same operacje dostępne przez Model Context Protocol i gRPC, a także REST) opisuje dokumentacja API Connect. Konfigurację potoku RoadRunner, wdrożenia oraz uwierzytelniania opisuje przewodnik po transporcie REST.

Bazowy adres URL i uwierzytelnianie

Transport REST nasłuchuje na hoście i porcie skonfigurowanych dla danego wdrożenia. Przy uruchomieniu lokalnym jest to http://localhost:8080; w środowisku produkcyjnym jest to adres wystawiony przed pulą procesów roboczych.

Uwierzytelnianie odbywa się za pomocą tokenu bearer. Klucz API należy wysyłać w nagłówku Authorization w każdym żądaniu do trasy objętej kontrolą poziomu dostępu:

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

Sondy żywotności i gotowości działające tylko do odczytu nie wymagają tokenu.

Operacje

Dostępność zależy od poziomu licencji. Rdzeń open source udostępnia operacje dotyczące dokumentów, renderowania, sesji i zadań. Podpisywanie, wypełnianie formularzy, redagowanie, porównywanie, sprawdzanie dostępności oraz optymalizacja wymagają edycji komercyjnej zainstalowanej obok serwera. Miarodajny zestaw dla danego wdrożenia zwraca punkt końcowy możliwości. Należy odpytać ten punkt końcowy, zamiast zakładać stałą listę.

Kondycja i cykl życia

Metoda	Ścieżka	Przeznaczenie
GET	/healthz	Sonda żywotności. Bez uwierzytelniania.
GET	/readyz	Sonda gotowości (zależności i pula procesów roboczych są gotowe). Bez uwierzytelniania.
GET	/api/v1/capabilities	Narzędzia i poziomy faktycznie udostępniane przez to wdrożenie. Należy odpytać ten punkt końcowy w pierwszej kolejności.

Renderowanie i dokumenty

Metoda	Ścieżka	Przeznaczenie
POST	/api/v1/render	Renderuje dokument z uporządkowanej listy operacji i zwraca plik PDF.
POST	/api/v1/extract-text	Wyodrębnia zawartość tekstową z pliku PDF.
POST	/api/v1/merge	Scala kilka wejściowych plików PDF w jeden dokument.
POST	/api/v1/split	Dzieli plik PDF na wiele dokumentów.

Zadania asynchroniczne

Metoda	Ścieżka	Przeznaczenie
POST	/api/v1/jobs	Przekazuje długotrwałą operację jako zadanie.
GET	/api/v1/jobs/{id}	Odpytuje status zadania.
GET	/api/v1/jobs/{id}/result	Pobiera wynik ukończonego zadania.

Sesje

Sesje utrzymują otwarty dokument przez kilka wywołań, dzięki czemu można budować go przyrostowo i wyrenderować jednorazowo na końcu.

Metoda	Ścieżka	Przeznaczenie
POST	/api/v1/sessions	Otwiera sesję.
GET / DELETE	/api/v1/sessions/{sessionId}	Sprawdza lub zamyka sesję.
POST	/api/v1/sessions/{sessionId}/pages	Dodaje stronę.
POST	/api/v1/sessions/{sessionId}/text	Dodaje tekst.
POST	/api/v1/sessions/{sessionId}/images	Dodaje obraz.
POST	/api/v1/sessions/{sessionId}/tables	Dodaje tabelę.
POST	/api/v1/sessions/{sessionId}/html	Dodaje wyrenderowany kod HTML.
POST	/api/v1/sessions/{sessionId}/font	Ustawia aktywną czcionkę.
POST	/api/v1/sessions/{sessionId}/render	Renderuje dokument sesji.

Operacje edycji komercyjnej

Te trasy są rejestrowane tylko wtedy, gdy zainstalowana jest odpowiednia edycja komercyjna. Niektóre z nich wymagają zatwierdzenia w procesie potwierdzania z udziałem człowieka; zobacz poziomy ryzyka.

Metoda	Ścieżka	Przeznaczenie
POST	/api/v1/sign	Nakłada podpis cyfrowy.
POST	/api/v1/fill-form	Wypełnia formularz interaktywny.
POST	/api/v1/redact	Redaguje zawartość.
POST	/api/v1/compare	Porównuje dwa dokumenty PDF.
POST	/api/v1/check-accessibility	Przeprowadza strukturalną kontrolę dostępności.
POST	/api/v1/optimize	Optymalizuje i zmniejsza dokument.

Model błędów

Transport REST używa kodów stanu HTTP o semantyce zdefiniowanej w RFC 9110: 2xx dla powodzenia, 4xx dla żądania, które wywołujący musi poprawić (400 nieprawidłowa treść, 401 brakujący lub nieprawidłowy token, 403 odmowa z powodu poziomu lub zatwierdzenia, 404 nieznana trasa lub zadanie, 409 konflikt idempotentności, 422 poprawnie sformułowane żądanie, którego silnik nie może przetworzyć), oraz 5xx dla błędu po stronie serwera. Odpowiedź 401 zawiera wyzwanie WWW-Authenticate.

Odpowiedzi błędów mają postać dokumentów application/problem+json zgodnych z RFC 9457 (Problem Details for HTTP APIs): stabilny type, krótki title, liczbowy status oraz czytelny dla człowieka detail. Dopasowuj według type, a nie według wartości detail. Definicje normatywne zawierają również RFC 9110 (HTTP Semantics) oraz RFC 9457.

Żądania zmieniające stan wysyłaj z nagłówkiem Idempotency-Key, aby ponowione żądanie zostało przetworzone tylko raz.

Specyfikacja do odczytu maszynowego

Pełny kontrakt jest opublikowany jako statyczny dokument OpenAPI 3.1:

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

Traktuj go jako jedyne źródło prawdy dla interfejsu REST:

1. Otwórz interaktywny eksplorator API — samodzielnie hostowaną dokumentację Scalar działającą w przeglądarce i wygenerowaną z tego kontraktu — aby zapoznać się z każdą operacją i wypróbować ją wraz ze schematami żądań i odpowiedzi.
2. Zaimportuj kontrakt do klienta zapytań, takiego jak Postman czy Insomnia.
3. Wygeneruj typowanego klienta dla swojego języka za pomocą generatora OpenAPI.

Dokument jest statycznym kontraktem przypiętym do wersji pakietu. Nie jest udostępniany przez aktywny punkt końcowy, dzięki czemu pozostaje stabilny między wdrożeniami.

Zobacz również

• Dokumentacja API Connect — pełny katalog narzędzi obejmujący MCP, REST i gRPC.
• Przewodnik po transporcie REST — potok RoadRunner, uwierzytelnianie tokenem bearer i routing według poziomów.
• Przegląd NextPDF Connect — czym jest serwer i jak go uruchomić.