株式会社renue
renueについて
renueは、AIで業務を実装する会社です
AIコンサルティングから図面AI・広告運用エージェント・コールセンターAIまで、実際に動いているサービスをご覧いただけます。renueが何をしている会社か、まずはサービス一覧からご確認ください。
API設計はなぜ重要なのか
API（Application Programming Interface）は、システム間のデータ連携と機能共有を実現するインターフェースです。SaaS連携、モバイルアプリ、マイクロサービス、AIエージェントなど、現代のソフトウェアアーキテクチャはAPIを中心に構築されています。
APIの設計品質は、開発者の生産性、システムの拡張性、セキュリティ、運用コストのすべてに影響します。一度公開したAPIは変更が難しいため、最初の設計が極めて重要です。
REST vs GraphQL｜どちらを選ぶか
| 項目 | REST API | GraphQL |
|---|---|---|
| 設計思想 | リソース指向（URLがリソースを表す） | クエリ指向（欲しいデータを指定） |
| エンドポイント | リソースごとに複数（/users, /orders等） | 通常はサービスごとに単一エンドポイント（例：/graphql） |
| データ取得 | サーバー側で構造を定義。フィールド選択を提供する設計も可能 | クライアントが欲しいフィールドを指定 |
| オーバーフェッチ | 返却項目の設計によっては不要なデータも返る | 要求フィールドを絞って抑制できる。不要な項目の要求までは防がない |
| キャッシュ | GET等でHTTPキャッシュを利用可能。認証・更新・キャッシュ制御の設計は必要 | GETのクエリではHTTPキャッシュも利用可能。要求・認証に応じた設計が必要 |
| 学習コスト | 低い（HTTP標準に準拠） | やや高い（スキーマ定義が必要） |
| 適した用途 | CRUD中心、公開API、シンプルなデータ構造 | 複雑なデータ関係、モバイルアプリ、ダッシュボード |
迷ったらRESTから始めるのが現実的です。RESTは広く理解されており、ツールやドキュメント生成（OpenAPI/Swagger）のエコシステムが充実しています。上表は設計上の比較例です。GraphQLのフィールド選択は返す項目を指定できますが、選択した項目がすべて用途に必要かはクライアント側で判断します。REST系でもJSON:APIのSparse Fieldsetsのように項目選択を設けられます。GraphQLのHTTP利用では、クエリのGET対応とキャッシュも説明されています。renueのバックエンド（FastAPI）でもREST APIを標準採用し、OpenAPIスキーマで自動ドキュメント生成を行っています。
REST API設計の10の原則
| # | 原則 | 内容 | 良い例 | 悪い例 |
|---|---|---|---|---|
| 1 | リソース指向のURL | URLは「リソース（名詞）」を表す | GET /users/123 | GET /getUser?id=123 |
| 2 | HTTPメソッドの正しい使用 | GET=取得、POST=作成、PUT=更新、DELETE=削除 | DELETE /users/123 | POST /deleteUser |
| 3 | 複数形のリソース名 | コレクションは複数形 | /users, /orders | /user, /order |
| 4 | 適切なHTTPステータスコード | 200=成功、201=作成、400=不正、404=未発見、500=サーバーエラー | 404 Not Found | すべて200で返す |
| 5 | ページネーション | 大量データはページ分割して返す | ?page=2&limit=20 | 全件を一括返却 |
| 6 | フィルタリングとソート | クエリパラメータで条件指定 | ?status=active&sort=-created_at | フィルタなしで全件返却 |
| 7 | 一貫したエラーレスポンス | 統一されたエラー形式 | {"error": {"code": "NOT_FOUND", "message": "..."}} | エラーごとに形式が異なる |
| 8 | バージョニング | 破壊的変更に対応するバージョン管理 | /api/v1/users | バージョンなしで互換性を壊す |
| 9 | レート制限 | APIの過剰利用を防止 | X-RateLimit-Remaining ヘッダー | 無制限アクセスを許可 |
| 10 | OpenAPIドキュメント | API仕様を機械可読な形式で公開 | Swagger UIで自動生成 | 仕様書なし |
認証・認可の設計
| 仕組み・形式 | 内容 | 適した用途 |
|---|---|---|
| APIキー | シンプルなキーをヘッダーに付与 | サーバー間通信、内部API |
| OAuth 2.0 | アクセストークンによる認可。スコープで権限制御 | サードパーティ連携、ユーザー認可 |
| JWT（JSON Web Token） | クレームを表すトークン形式。署名・暗号化等と検証を組み合わせる | OIDCのIDトークンや、認可用アクセストークン等の形式として利用 |
| SSO（シングルサインオン） | 1つのアカウントで複数サービスにログイン | エンタープライズ、SaaS |
セキュリティの鉄則：秘匿すべきAPIキーやクライアントシークレットはフロントエンドに埋め込まず、サーバー側で管理します。表の各項目は同じ階層の方式ではありません。OAuth 2.0は認可の枠組み、JWTはトークン形式、SSOは複数サービスへのログインをまとめる仕組みです。OpenID Connect（OIDC）はOAuth 2.0の上に認証を定義します。JWTは署名だけでなく、許可したアルゴリズム、発行者、宛先、有効期限等を確認し、保護対象ごとの権限も検証します。秘密を持つバックエンド経由のプロキシは実装の一案で、意図して公開する情報APIと保護対象APIを区別します（OWASP REST Security Cheat Sheet）。
バージョニング戦略
| 方式 | 内容 | メリット | デメリット |
|---|---|---|---|
| URLパス | /api/v1/users | 明確、キャッシュしやすい | URLが冗長 |
| ヘッダー | Accept: application/vnd.api+json;version=1 | URLがクリーン | 発見しにくい |
| クエリパラメータ | /api/users?version=1 | 実装が簡単 | キャッシュに影響 |
URLパス方式（/api/v1/）が最も推奨されます。明確で分かりやすく、ドキュメントやテストでも扱いやすいためです。
AI時代のAPI設計｜MCP対応
AIエージェントがAPIを自律的に呼び出す時代において、API設計に新たな考慮事項が加わっています。
| 考慮事項 | 内容 |
|---|---|
| MCPサーバー対応 | AIエージェントが自律的にAPIを発見・呼び出せるようMCPプロトコルに準拠 |
| ツール説明の自然言語化 | APIの機能を自然言語で記述し、AIが「いつ使うべきか」を判断できるように |
| べき等性の担保 | AIの再試行で二重処理が起きないよう、冪等性を設計に組み込む |
| エラーメッセージの明確化 | AIが自己修正できるよう、エラーの原因と対処法を詳細に返す |
| レート制限の透明化 | AIがAPI利用量を管理できるよう、レート制限情報をレスポンスヘッダーに含める |
renueでは、自社のバックエンドAPIをMCPサーバーとしても公開しています。一般的な用途の例として、Slack検索、プロジェクト管理、SEO分析、広告運用などをAIエージェントからAPI経由で呼び出す設計が考えられます。呼出し可能な範囲や承認条件は、用途と権限に応じて定めます。
API設計のアンチパターン
| アンチパターン | 問題 | 正しい設計 |
|---|---|---|
| 動詞をURLに含める | /getUsers, /createOrder | HTTPメソッドで操作を表現（GET /users, POST /orders） |
| すべて200で返す | エラーもステータス200で返し、bodyにエラー情報 | 適切なHTTPステータスコードを使用 |
| 内部実装の露出 | DBカラム名やスタックトレースをレスポンスに含める | APIスキーマとDB構造を分離、エラー情報を抽象化 |
| バージョン管理なし | 破壊的変更が既存クライアントを壊す | URLパスでバージョニング（/api/v1/） |
| 保護対象APIの認証・認可漏れ | 非公開情報や更新操作に無権限でアクセスできる | 対象に合う認証と権限検証。公開情報APIは意図した公開範囲・レート制限等を設計 |
よくある質問（FAQ）
Q. REST APIとGraphQL、どちらを選ぶべき？
CRUD中心のシンプルなAPIならREST、複雑なデータ関係や柔軟なデータ取得が必要ならGraphQLが適しています。両方を併用する設計も選択肢です。例えば外部公開APIはREST、フロントエンド向けの柔軟なデータ取得はGraphQLと分け、利用者・キャッシュ・運用負荷に合わせて検討します。迷ったらRESTから始めましょう。
Q. APIドキュメントはどう管理すべき？
OpenAPI（Swagger）仕様でAPIを定義し、コードから自動生成するのがベストプラクティスです。FastAPIはルート定義やPythonの型宣言等からOpenAPIを生成し、標準でSwagger UIを利用できます。公開URLや無効化は設定可能です。NestJSは@nestjs/swaggerを導入し、SwaggerModule.createDocumentとsetup等を設定してスキーマ生成・UI表示を行います。手書き資料でも変更と同期する運用は可能ですが、自動生成は更新漏れを減らす方法の一つです。本記事では「コードがドキュメント」のアプローチが推奨です。
Q. APIのテストはどうすべき？
①ユニットテスト（各エンドポイントの入出力を検証）、②統合テスト（DB連携を含むエンドツーエンドの動作確認）、③コントラクトテスト（APIの仕様が変わっていないことを検証）の3層で行います。CI/CDパイプラインに組み込み、PRごとに自動実行するのが標準です。
まとめ：良いAPI設計が良いシステムの基盤になる
API設計は、リソース指向のURL、HTTPメソッドの正しい使用、適切な認証、バージョニング、ドキュメントの自動生成を基本原則として押さえることが重要です。AI時代においてはMCP対応やAIフレンドリーなエラー設計も新たな考慮事項となっています。
株式会社renueでは、APIを中心としたシステム設計やAIプラットフォームの構築を行っています。API設計やシステムアーキテクチャにご関心のある方は、ぜひお気軽にお問い合わせください。