NextPDF Connect — REST トランスポート

概要

REST トランスポートは、RoadRunner の HTTP ワーカープール内で bin/nextpdf-server を実行します。API は OpenAPI 3.1 ドキュメントで記述され、ヘルスチェック以外のすべてのリクエストを bearer API キーで認証し、Pro および Enterprise のルートはインストール済みのティアに応じてゲートされます。

インストール

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

概念の概要

各リクエストは、ハンドラーに到達する前に PSR-15 ミドルウェアパイプラインを通過します。パイプラインでは、リクエスト ID の割り当て、ボディサイズおよびティアペイロードの制限、CORS、認証、ケイパビリティ認可、IP 単位およびクライアント単位のレート制限、冪等性、タイムアウトを処理します。レスポンスを自身で生成できない PSR-15 ミドルウェアは、与えられたリクエストハンドラーに処理を委譲します（PSR-15 §2.2 MiddlewareInterface::process、条項 psr_15_handlers#2.2.p14）。パイプラインが渡す PSR-7 リクエストオブジェクトはイミュータブルであり、状態を変更する呼び出しはその場で変更せず、新しいインスタンスを返します（PSR-7 §3.2.1）。

ルートテーブルは起動時に構築され、その内容はランタイム条件に依存します。コアルートは常に登録されます。Pro の操作ルートは、Pro または Enterprise がインストールされている場合にのみ登録されます。Enterprise のルートは、Enterprise がインストールされている場合にのみ登録されます。セッションルートは、セッションが有効になっている場合にのみ登録されます。

API サーフェス

常に登録されるルート

メソッド	パス	認証
`GET`	`/healthz`	なし（liveness）
`GET`	`/readyz`	なし（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

ヘルスプローブは、安全で読み取り専用のエンドポイントです。状態変更を一切引き起こしません。これは RFC 9110 が安全なメソッドとして定義する性質です（RFC 9110 §9.2.1）。

ティアでゲートされるルート（ランタイム依存）

対応するパッケージがインストールされている場合にのみ登録されます。

Pro または Enterprise がインストールされている場合： /api/v1/sign、/fill-form、/redact、/compare、/check-accessibility、/optimize。
Enterprise がインストールされている場合： /api/v1/compliance-check、/forensic-analyze、/ai-certify。

インストールされていないティアのルートへのリクエストは、ルーティングされません。ルートが要求するティアより低いティアのキーで認証されたリクエストは 403 で拒否されます。署名が公開されている場合、Pro を備えた NextPDF Connect が提供する署名は PAdES baseline-B（B-B）のみです。長期検証プロファイルは、このトランスポートのサーフェスには含まれません。

OpenAPI コントラクト

REST サーフェスは、静的な OpenAPI 3.1 ドキュメントとして、パッケージ内の openapi/nextpdf-connect.yaml に同梱されます。そのセキュリティスキームは、Authorization ヘッダー内の bearer API キーです（Bearer npk_live_{kid}_{secret}）。エラーレスポンスは RFC 7807 の problem-details ドキュメントであり、条件ごとに type URL を持ちます。

OpenAPI レンダリング — Scalar

ドキュメントプラットフォーム計画 §12 に従い、集約ドキュメントサイトはこの OpenAPI ドキュメントを Scalar（@scalar/api-reference）でレンダリングします。これは REST 統合ページに <ScalarApiReference src=…> コンポーネントとして埋め込まれます。信頼できる唯一の情報源は、パッケージの openapi/nextpdf-connect.yaml です。サイトのビルドでは、並行するエンドポイントリファレンスを手作業で維持するのではなく、これを取得してレンダリングします。サーバーには、ランタイムで OpenAPI を配信するエンドポイントは含まれません。このドキュメントはビルド時のアーティファクトです。

コードサンプル — クイックスタート

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

コードサンプル — 本番環境

REST と gRPC のトランスポートが 1 つのスーパーバイザーを共有する構成で、結合プロファイルを実行します。

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

エッジケースと注意点

パッケージが存在しない場合、ティアルートは 404 を返します。 ルートが登録されていないため、ルーターはマッチしません。これは想定どおりの動作であり、認証失敗ではありません。
401 と 403 の違い。 401 は有効なキーがないことを意味します（レスポンスには、RFC 9110 §11.6.1 に従って WWW-Authenticate: Bearer ヘッダーが含まれます）。403 は、キーは有効でも、そのティアではその操作を実行する権限がないことを意味します。
セッションはデフォルトで無効です。 /api/v1/sessions/... ルートは、NEXTPDF_SESSIONS_ENABLED=true でツールが利用可能な場合にのみ存在します。
高リスクの操作は依然としてゲートされます。 ApprovalRequired ツールをトリガーする REST 呼び出しは、MCP と同じ human-in-the-loop ゲートを通過します。/connect/hitl-risk-tiers/. を参照してください。

パフォーマンス

各 RoadRunner ワーカーは、一度に 1 つのリクエストを処理します。長時間の同期レンダリングはワーカーを占有します。低速な処理には非同期ジョブルートを使用し、ワーカーを解放してください。観測されたレイテンシーに合わせてプールサイズを設定してください。/connect/production-usage/. を参照してください。

セキュリティに関する注記

REST リスナーの手前で TLS を終端してください。この設計では、平文の HTTP にバインドし、上流での終端処理を前提としています。十分にランダムな npk_live_ キーで認証し、キーはソース管理の外に保存して、ホットリロード対応のファイルキーストアを優先してください。/connect/security-and-operations/. を参照してください。

適合性

主張	出典	`reference_id`
`401` における `WWW-Authenticate` チャレンジの必須包含	RFC 9110 §11.6.1
安全なメソッドの読み取り専用性	RFC 9110 §9.2.1
PSR-7 リクエストのイミュータブル性	PSR-7 §3.2.1
レスポンスを生成できないミドルウェアによる、与えられたリクエストハンドラーへの処理委譲	PSR-15 §2.2 `MiddlewareInterface::process`（`psr_15_handlers#2.2.p14`）

商用コンテキスト

署名、墨消し、比較、アクセシビリティ、最適化、コンプライアンスのルートは、nextpdf/premium がインストールされている場合にのみ登録されます。認証モデルは変わりません。アクセス権はキーのティアによって決まります。