# OpenAPI 仕様

> /v1/openapi.json から Nodaro の OpenAPI 3.1 仕様をダウンロードし、対応するエンドポイントを確認して、Go、Rust、Python など向けの型付きクライアントを生成します。

Source: https://nodaro.ai/ja/docs/developers/api/openapi

**Nodaro OpenAPI 仕様**は、Nodaro REST API のコア部分を機械可読な形式で記述した、OpenAPI 3.1 の仕様です。稼働中のサーバーが直接配信します。Go、Rust、Python など、OpenAPI のジェネレーターがある言語で型付きのクライアントを生成するために使うほか、OpenAPI を読み取れるどのツールでも API を確認できます。TypeScript と JavaScript では、[SDK](https://nodaro.ai/docs/developers/sdk) がそのまま使えるクライアントです。

## 仕様を取得する
```bash
curl -s https://app.nodaro.ai/v1/openapi.json -o nodaro-openapi.json
```

仕様は公開されているため、トークンは不要です。キャッシュされる期間は 5 分間です。セルフホスティング環境も、同じパス `/v1/openapi.json` でその環境自身の仕様を配信します。**設定 › APIトークン**のページにも、仕様へのリンクがあります。

## 仕様が対象とする範囲
この仕様は、API の**厳選された一部**です。すべてのルートではなく、自動化のコア部分を記述しています。対象は次のとおりです。

| 分野 | パス |
| --- | --- |
| ワークフロー | `GET /v1/projects/{projectId}/workflows`、`POST /v1/workflows/{id}/run`、`POST /v1/workflows/{id}/move` |
| ジョブ | `GET /v1/jobs/{id}`、`GET /v1/jobs/{id}/status` |
| ノードの検出 | `GET /v1/nodes`、`GET /v1/nodes/{type}` |
| 生成 | `POST /v1/generate-image`、`POST /v1/generate-video` |
| OAuth | `POST /v1/oauth/token`、`GET /v1/oauth/app-info`、および `/v1/oauth/plugin/` 以下のプラグイン接続ルート |
| クレジット | `POST /v1/credits/model-costs`、`POST /v1/credits/video-pro-estimate` |

共有スキーマを 4 つ定義しています。`WorkflowSummary`、`Job`、`JobStatus`、`NodeDescriptor` です。サーバーは自身のルート定義から仕様を生成するため、正確な一覧は実際のファイルを確認してください。

利用する際に知っておくべき点がいくつかあります。

- **セキュリティスキームは 1 つだけです**。`bearerAuth` は、HTTP のベアラートークンです。仕様ではフォーマットを `JWT` としていますが、このスキームは個人用 API トークン、OAuth アクセストークン、セッションの JWT のいずれも受け付けます。[認証](https://nodaro.ai/docs/developers/api/authentication)を参照してください。
- **サーバーは相対パスです**。仕様のサーバーは `/` なので、クライアントを作成するときに、`https://app.nodaro.ai` のようなベース URL を設定してください。
- **ノードの検出ルートは公開されています**。仕様ではすべてのパスに `bearerAuth` の指定がありますが、`GET /v1/nodes` と `GET /v1/nodes/{type}` は、トークンなしでも応答します。
- **生成のフィールドはすべて記載されています**。`POST /v1/generate-image` と `POST /v1/generate-video` には、`connectedReferences`、`direction`、`subject` を含む、リクエストボディ全体が記載されています。フィールドの内容については、[ノード](https://nodaro.ai/docs/developers/api/nodes)を参照してください。

## クライアントを生成する
```bash
# Go
oapi-codegen -generate types,client -package nodaro https://app.nodaro.ai/v1/openapi.json

# Rust
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g rust -o nodaro-rs

# Python
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g python -o nodaro-py
```

その後、クライアントにベース URL を設定し、すべてのリクエストで `Authorization: Bearer <token>` を送信します。それ以外は、ほかのページで説明している内容と同じです。JSON 形式のボディ、[エラー](https://nodaro.ai/docs/developers/api/errors)にある `{ "error": { "code", "message" } }` の形式、そして[ジョブ](https://nodaro.ai/docs/developers/api/jobs)での結果のポーリングです。

## 仕様に含まれないエンドポイントを呼び出す
REST API は、仕様に記載がない部分でも、どの言語からでも使えます。ベアラートークンを送り、JSON を送信して JSON を受け取るだけです。

- **どのノードも、同じルートです**。`POST /v1/{node-type}` に、ノードの設定をボディとして送ると、仕様にある 2 つだけでなく、どのノードも実行できます。ノードのフィールドは、`GET /v1/nodes/{type}` の `inputSchema` と、[ノードリファレンス](https://nodaro.ai/docs/nodes)のそのノードのページから確認できます。
- **それ以外のエンドポイントは、このドキュメントの各ページで説明しています**。[ワークフロー](https://nodaro.ai/docs/developers/api/workflows)や[実行](https://nodaro.ai/docs/developers/api/executions)から、[アップロード](https://nodaro.ai/docs/developers/api/uploads)や[クレジット](https://nodaro.ai/docs/developers/api/credits)までです。生成したクライアントの生のリクエストメソッドか、任意の HTTP ライブラリで呼び出してください。

## Frequently asked questions

### Nodaro の OpenAPI 仕様は、どこにありますか？

Nodaro Cloud では、https://app.nodaro.ai/v1/openapi.json にあります。公開されているため、トークンは不要です。セルフホスティング環境も、同じパスでその環境自身の仕様を配信します。

### OpenAPI 仕様は、Nodaro のすべてのエンドポイントを対象としていますか？

いいえ。この仕様は、API の一部を厳選して対象としています。自動化のコア部分、ワークフローの実行、ジョブのステータス、ノードの検出、画像と動画の生成、OAuth のトークン交換、クレジット消費量の確認が含まれます。それ以外のエンドポイントは、このドキュメントの各ページで説明しています。

### 仕様に含まれていないノードは、どうすれば呼び出せますか？

どのノードも、同じルートに従います。POST /v1/ の後にノードタイプを付け、ノードの設定をボディに入れます。ノードのフィールドは GET /v1/nodes/:type から読み取り、生成したクライアントの生のリクエストメソッドか、任意の HTTP ライブラリでリクエストを送信します。

### 仕様が宣言している認証方式は、どれですか？

1 つだけです。bearerAuth という、HTTP のベアラートークンです。仕様ではフォーマットを JWT としていますが、実際には個人用 API トークン、OAuth アクセストークン、セッションの JWT のいずれも受け付けます。