Connect REST API リファレンス

概要

NextPDF Connect は、ツールレジストリを REST トランスポートとして HTTP 経由で公開し、OpenAPI 3.1 コントラクトで記述します。このページは、そのサーフェスのリファレンスです。ベース URL、認証方法、操作グループ、エラーモデルを扱います。完全な機械可読仕様が公開されているため、手作業でコピーすることなく、対話型エクスプローラー、クライアントジェネレーター、またはリクエストクライアントに読み込めます。

トランスポートに依存しないツールカタログ（REST に加え、Model Context Protocol や gRPC でも使える同じ操作）については、Connect API リファレンスを参照してください。RoadRunner パイプライン、デプロイメント、認証のセットアップについては、REST トランスポートガイドを参照してください。

ベース URL と認証

REST トランスポートは、デプロイメントで構成されたホストとポートでリッスンします。ローカル実行では http://localhost:8080、本番環境ではワーカープールの前段にあるアドレスになります。

ベアラートークンで認証します。ティアでゲートされたルートへのすべてのリクエストでは、API キーを Authorization ヘッダーで送信します。

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

読み取り専用の liveness プローブと readiness プローブには、トークンは必要ありません。

操作

利用可否はティアでゲートされます。オープンソースのコアには、document、render、session、job の各操作が含まれます。署名、フォーム記入、墨消し、比較、アクセシビリティチェック、最適化には、サーバーと併せてインストールされた商用エディションが必要です。特定のデプロイメントで正式に利用できるセットは、capabilities エンドポイントから返されます。固定のリストを前提にせず、このエンドポイントをクエリしてください。

ヘルスとライフサイクル

メソッド	パス	目的
GET	`/healthz`	liveness プローブ。認証なし。
GET	`/readyz`	readiness プローブ（依存関係とワーカープールが準備完了）。認証なし。
GET	`/api/v1/capabilities`	このデプロイメントが実際に公開しているツールとティア。最初にクエリすべきエンドポイント。

レンダリングとドキュメント

メソッド	パス	目的
POST	`/api/v1/render`	順序付けされた操作リストからのドキュメントレンダリングと PDF の返却。
POST	`/api/v1/extract-text`	PDF からのテキストコンテンツ抽出。
POST	`/api/v1/merge`	複数の PDF 入力を 1 つのドキュメントへ結合。
POST	`/api/v1/split`	PDF の複数ドキュメントへの分割。

非同期ジョブ

メソッド	パス	目的
POST	`/api/v1/jobs`	長時間実行される操作のジョブ送信。
GET	`/api/v1/jobs/{id}`	ジョブステータスのポーリング。
GET	`/api/v1/jobs/{id}/result`	完了したジョブ結果の取得。

セッション

セッションでは、複数の呼び出しにわたってドキュメントを開いたまま保持できるため、段階的に構築し、最後に一度だけレンダリングできます。

メソッド	パス	目的
POST	`/api/v1/sessions`	セッションの開始。
GET / DELETE	`/api/v1/sessions/{sessionId}`	セッションの検査または終了。
POST	`/api/v1/sessions/{sessionId}/pages`	ページの追加。
POST	`/api/v1/sessions/{sessionId}/text`	テキストの追加。
POST	`/api/v1/sessions/{sessionId}/images`	画像の追加。
POST	`/api/v1/sessions/{sessionId}/tables`	テーブルの追加。
POST	`/api/v1/sessions/{sessionId}/html`	レンダリングされた HTML の追加。
POST	`/api/v1/sessions/{sessionId}/font`	アクティブなフォントの設定。
POST	`/api/v1/sessions/{sessionId}/render`	セッション内ドキュメントのレンダリング。

商用エディションの操作

これらのルートは、対応する商用エディションがインストールされている場合にのみ登録されます。一部は、human-in-the-loop 確認フローによる承認ゲートの対象です。リスクティアを参照してください。

メソッド	パス	目的
POST	`/api/v1/sign`	電子署名の適用。
POST	`/api/v1/fill-form`	インタラクティブフォームへの記入。
POST	`/api/v1/redact`	コンテンツの墨消し。
POST	`/api/v1/compare`	2 つの PDF ドキュメントの比較。
POST	`/api/v1/check-accessibility`	構造的なアクセシビリティチェックの実行。
POST	`/api/v1/optimize`	ドキュメントの最適化とサイズ削減。

エラーモデル

REST トランスポートは、RFC 9110 で定義されたセマンティクスに従い、HTTP ステータスコードを使用します。2xx は成功、4xx は呼び出し側で修正すべきリクエスト（400 は形式不正のボディ、401 はトークンの欠落または無効、403 はティアまたは承認の拒否、404 は不明なルートまたはジョブ、409 は冪等性の競合、422 は形式は正しいがエンジンが処理できないリクエスト）、5xx はサーバー側の障害を表します。401 レスポンスには WWW-Authenticate チャレンジが含まれます。

エラーボディは、RFC 9457（Problem Details for HTTP APIs）に準拠した application/problem+json ドキュメントです。安定した type、簡潔な title、数値の status、人が読める detail を含みます。照合は type で行い、detail 文字列では行わないでください。規範的な定義については、RFC 9110（HTTP Semantics）および RFC 9457 も参照してください。

状態を変更するリクエストは、Idempotency-Key ヘッダーを付けて送信し、再試行されたリクエストが一度だけ処理されるようにしてください。

機械可読仕様

完全なコントラクトは、静的な OpenAPI 3.1 ドキュメントとして公開されています。

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

このコントラクトを REST サーフェスの信頼できる唯一の情報源として使用してください。

まず、インタラクティブ API エクスプローラーを開いてください。これは、このコントラクトから生成された、ブラウザー内で動作するセルフホスト型の Scalar リファレンスであり、各操作をリクエストおよびレスポンスのスキーマとともに確認し、試すことができます。
Postman や Insomnia などのリクエストクライアントにインポートします。
OpenAPI ジェネレーターを使用して、お使いの言語向けの型付きクライアントを生成します。

このドキュメントは、パッケージ内でバージョン固定された静的なコントラクトです。ライブエンドポイントから提供されないため、デプロイメントをまたいでも安定したままです。