AI-Ready API 〜 AI時代に求められるAPIの作り方

2026.1.13 オンライン勉強会（ウェビナー）で使用した資料

Transcript

1. All rights reserved by Postman Inc 川崎庸市 テクノロジー・エバンジェリスト 2026.01.13 AIReady API 〜 AI時代に求められるAPIの作り方
2. 川崎 庸市 / Yoichi Kawasaki @yokawasa Postman株式会社にて、同社製品の導入支援、社外登壇、執筆活動を通じて、同社製品ならび にAPI技術の啓蒙・教育に取り組む。加えて、SaaSスタートアップの技術顧問も務める。以前は、 国内EC事業会社や外資系ソフトウェアベンダーにて幅広いエンジニアリング業務に従事。
3. お話すること APIは他のソフトウェアと同様に、一度作って終わりではなく、継続的に使われること を前提に、ライフサイクル全体で考える必要があります。また、利用者にとって使いや すくなければ、APIの価値は十分に発揮されません。 本セッションでは、AI時代に求められる「人にもAIにも良いAPI」を実現するために、 AI特有の考慮点 と、API設計・テスト・ドキュメンテーション の実践ポイントを紹介し ます。 ⚠ 本セッションでは Web API（REST API）を前提に説明しますが、紹介する考え方やプラクティ スは、他のAPIスタイルにも適用可能です。
4. はじめに
5. 2025年、AIやMCPというキーワード を聞かなかった日は無かったかもしれません ※ - MCP  Model Context Protocol
6. AI時代においても、なぜAPIが重要なのか？
7. APIはAIの手足であり、AIの"思考"を支える存在である APIs are the hands and legs that power the “thinkingˮ that the AI is doing Abhinav Asthana, Postman CEO & Co-Founder Generative AI and the impact on APIs and software development https://blog.postman.com/generative-ai-and-the-impact-on-apis-and-software-development/
8. APIはこれまで以上に重要になっている APIは、システムと他のサービスやデータソースとの連携を可能にし、効率的なデータ処 理とインタラクションを実現するための基盤
9. AI時代においても、なぜAPIが重要なのか？ AIがどれだけ高度な判断を行えても、その力を外の世界とつなぐのはAPIであり、AI時 代においても品質の高いAPIの提供が鍵となります • AIエージェントは直接業務を実行できない • MCP※ は「橋渡し」であって「実行主体」ではない • 実際の業務処理・ビジネスロジックはAPIを経由して実行する MCP API AIエージェント ※ - MCP  Model Context Protocol AIエージェント API / 外部ツール MCP Client MCP Server Model Context Protocol
10. AIReady APIとは何か？ （ここでの）AIReady APIの定義 人間ばかりでなくAIにもやさしく、安全かつ継続的に利 用できるように管理されているAPI
11. AIエージェントの行動モデルから探る AIにとって扱いやすいデータ
12. AIエージェントとLLMの関係 LLMが推論と判断を担い、AIエージェントがその判断を実行に移して目標を達成する LLM（頭脳） - 推論 - 計画立案 AIエージェント - LLMに問い合わせ - 外部ツール実行 - コンテキスト管理 インプット アウトプット
13. APIの使い方: 人間 vs. AIエージェント 人間は「何をしたいのか、どのAPIを使うか」が明確だが、AIは「目標とコンテキスト」から出発 目標とコンテキスト 何をすべきか思考 ツール選択と順序決定 動的にAPI呼び出し (目標) やりたいことが明確 どのAPIか分かっている API仕様書読んで、詳細決定 決められた順序でAPI呼び出し Reasoning 推論
14. AIエージェントの行動モデル 多くのAIエージェントの行動モデルはReAct的 • ユーザーの目標やプロンプトを受け取る • → 内部で思考プロセス Chain-of-Thought) を展開 • → 必要に応じてツール API、DB、検索など)を実行 • → 観察（Observation） • → 次のステップを決定 ReAct Reaction + Action) ReAct: SYNERGIZING REASONING AND ACTING IN LANGUAGE MODELS (Yao et al., 2022) https://arxiv.org/pdf/2210.03629 AIエージェントの行動モデルを助ける情報が大切 • 意味や目的が明確な情報 • 一貫性・予測可能性がある情報 ※ ReAct的とはあくまで行動と思考の対話ループを持つという意味で Start Thought Action Observation End
15. Affordance (アフォーダンス) • UX・デザイン文脈で「ある物体がどのように使えるかを直感的に示す特性」として知られている。例：ボ タンは「押すもの」、椅子は「座るもの」 • LLMにとってAffordance力が高いとは、 意味や目的の理解のための明確な情報（ヒントや構造）が 含まれていること ⇒ 機械可読、自己記述的、セマンティックな情報 “Affordances provide strong clues to the operations of things. Plates are for pushing. Knobs are for turning. Slots are for inserting things into. Balls are for throwing or bouncing. When affordances are taken advantage of, the user knows what to do just by looking: no picture, label, or instruction needed.ˮ Affordanceが正しく活用されていれば、ユーザーは見るだけで何を すべきか分かる。図もラベルも説明書も不要 — Donald A. Norman, “The Design of Everyday Thingsˮ 1988 ※自己記述的 = Self-descriptive そのまま読んでわかる ※セマンティック = 意味や目的が明確
16. 推論コスト・トークン制限 • LLMの推論コスト、トークン制限を考えてデータを提供する必要がある • LLMの性能をより効果的に引き出すには、大量の生データをそのまま渡すのではなく、LLMが扱い やすいように集計・加工・構造化されたなデータを渡すのが効果的 LLMが苦手なデータ • 大量データ • ノイズの多いデータ • 一貫性のないデータ • 構造化されてないデータ 対策（集計・加工） • 絞り込み • ノイズ除去 • 構造化 • フォーマット変換 効果 • 応答速度向上 • 推論の精度向上 • コスト削減 Materialized Viewパターンは 有効なアプローチの１つ Materialized View pattern　 https://learn.microsoft.com/en-us/azure/arc hitecture/patterns/materialized-view
17. AIに対して特に考慮が必要な特性
18. AIに対して特に考慮が必要な特性 • Affordance力 (機械可読で明確なドキュメント、メタデータ、エラーメッセージ、など） • 一貫性 AIにとって予測可能性がある命名規則、スキーマ構造、など) • 冪等性 (何回実行しても結果が変わらないこと) • 発見可能性 (見つけやすいこと) • パフォーマンス・セキュリティ • 推論コスト・トークン制限対策（専用のタスク用API、的確な結果に絞れるオプション） ここで紹介する特性は、 AIのためだけのものではなく、人間にとっても本質的に重要な特性です
19. API仕様 = Single Source of Truth • 人にとってAPI仕様はSingle Source of Truth (信頼できる唯一の情報)。 ◦ API (仕様) ファーストでは、モック、テスト、コード（ SDK、スタブ）を生成する重要な情報源 • AIにとってもAPI仕様はAPIのAffordance力や発見可能性を支える重要な情報源 • これまでも自動生成の観点で機械可読であることは重要だったが、AI時代では機械可読であること は必須となったと言える 人間だけが読める独自フォーマットのAPI仕様は卒業し、AIも使えるAPI仕様へ。AI時代のAPIは、 標準化・機械可読な形式が鍵となる
20. APIのAIReady対策 - Affordance力を高める • 機械可読・自己記述的・セマンティックなAPI仕様ドキュメントの整備 ◦ OpenAPI、Postmanコレクション、GraphQL schemaなど • メタデータの整備 ◦ OperationId (操作識別用文字列) を明確化 OpenAPIの場合) ◦ 説明フィールド (summary, description ) ◦ パラメーター・スキーマ構造詳細 ◦ サンプルデータ ◦ 認証・認可 • エラーハンドリング用の情報 ◦ ステータスコード ◦ エラーメッセージ
21. APIのAIReady対策 - Affordance力を高める OpenAPIのメタデータ整備：OperationId、説明フィールド、パラーメータ・スキーマ構造 明確なoperationId (操作識別用文字列) 説明フィールド (summary, description） パラメータの詳細 （説明、型、制限、など） Stripe API OpenAPI https://github.com/stripe/openapi/blob/master/openapi/spec3.yaml
22. APIのAIReady対策 - Affordance力を高める エラーハンドリング用の情報の提供: ステータスコード, エラーメッセージ • HTTP標準のステータスコード（400, 500…） • エラーの原因 (明確かつ具体的な自然言語での説明) • 次のアクションを判断できる情報 (再試行、回避可能性、など) • エラーのサンプル Stripe APIのRate Limitエラー（HTTP ステータスコード: 429） Stripe API error handling https://stripe.com/docs/error-handling
23. APIのAIReady対策 - 一貫性 命名規則、スキーマ構造など一貫性 (予測可能性) のあるAPIの提供 • AIエージェントの行動モデルはReAct的で、パターン・規則性に従い判断する • 一貫性が崩れるとAPIを正しく認識できなくなる可能性がある 一貫性のポイント • 命名の一貫性: API探索・目的理解が ◦ 悪例: /v1/users/{id} vs. /api/2/orders/{id} • 引数の一貫性: パラメータ設定の誤りを防げる ◦ 悪例: uid vs. user_id • エラー構造の一貫性: 後続のアクション（リトライなど）の判断が容易になる • レスポンス形式の一貫性: 後続のアクションの推論がスムーズになる
24. APIのAIReady対策 - 冪等性 冪等性 Idempotency、何回実行しても結果が変わらない特性)を担保する • AIエージェントは推論の過程で同じ処理を繰り返し実行(リトライ)する傾向がある • 冪等性がないAPIは想定しないデータの不整合を起こす可能性がある ◦ 重複注文・送金、大量のメール誤送信・・・ APIのCRUD処理における冪等性 • 一般的に冪等性のあるメソッド: GET, PUT, DELETE, HEAD, OPTIONS • POSTでも冪等性キーIdempotency-key)を活用した冪等性の担保は可能 ◦ Stripe APIでは冪等性キーを活用したPOSTの冪等性も標準的にサポート ◦ Stripe APIの冪等リクエスト https://docs.stripe.com/api/idempotent_requests
25. APIのAIReady対策 - 発見可能性 • AIにとって発見可能性 Discoverability) のないAPIは存在しないも同然 • 機械可読で分かりやすいメタデータ、発見可能なエンドポイントが必要 Postman Developers Guide to AIReady APIs https://www.postman.com/ai/ai-ready-apis/ 発見可能性のポイント • 機械可読なAPI仕様の公開 ◦ OpenAPI、Postman コレクション、GraphQL Schema、など • APIカタログへの登録・カタログ整備 ◦ AI用API探索のベースとなるAPIカタログに登録（Postman API Network, SwaggerHub、など） • Affordance力の高いメタデータ ◦ セマンティックで自己記述的なメタデータ ◦ 認証・認可のわかりやすさ・使いやすさは特に大切
26. APIのAIReady対策 - 推論コスト・トークン制限対策 LLMの推論コスト・トークン制限対策として、有効と思われる案 • タスク特化型APIの用意 ◦ リソース指向ではなくなるものの、LLMが目的特化型で要求できるAPIの用意 • 検索APIの用意 ◦ ピンポイントな結果が取得できるAPIの用意 • 出力フィルター・オプションの追加 ◦ fieldsクエリパラメータで出力フィールド制御 ◦ LLM向けに要約 or 少量データを返すオプションを用意 GET /users/{id}?fields=id,name { "id": "12345", "name": "My Example" } GET /users/{id} { "id": "12345", "name": "My Example", "email": "my@example.com", "address": { "street": "123 Some St", "city": "Example City" }, … "created_at": "20250718T120000Z" }
27. APIをライフサイクル全体で考える
28. AIReady APIとは何か？ （ここでの）AIReady APIの定義 人間ばかりでなくAIにもやさしく、安全かつ継続的に利 用できるように管理されているAPI 再掲
29. APIをライフサイクル全体で考える 定義 設計 開発 テスト セキュリティ デプロイ 監視・観測 ビジネス システム Security ・・・ ドキュメント コード管理 システム設定 モック API Contracts (スキーマ) APIサーバー 開発 API Gateway 開発 セキュリティ テスト 要件 generate パフォーマンス テスト Contracts テスト E2E テスト ソースコード 成果物 commit 自動テスト APIサーバー Build/Deploy API Gateway Build/Deploy CI/CD 配布 モニター アラート APM レポート APIカタログ API 開発ポータル trigger ユーザー フィードバック Feedback loop UIテスト Stub generate
30. APIをライフサイクル全体で考える 定義 設計 開発 テスト セキュリティ デプロイ 監視・観測 ビジネス システム Security ・・・ ドキュメント コード管理 システム設定 モック API Contracts (スキーマ) APIサーバー 開発 API Gateway 開発 セキュリティ テスト 要件 generate パフォーマンス テスト Contracts テスト E2E テスト ソースコード 成果物 commit 自動テスト APIサーバー Build/Deploy API Gateway Build/Deploy CI/CD 配布 モニター アラート APM レポート APIカタログ API 開発ポータル trigger ユーザー フィードバック Feedback loop UIテスト Stub generate
31. API設計の実践ポイント
32. API設計とは？ • APIがデータや機能をAPI利用者にどのように提供するかを決めるプロセス • このプロセスで決定した内容をAPI仕様（APIコントラクト）として文書化 • 良いAPI設計＝「利用者のニーズを満たすこと」が目的に検討し、その結果をAPI仕様に反映 • 目的 • ユースケース（誰が、何を、どう操作して、何を実 現できるか、etc.） • 利用条件 • 非機能要件 • APIが扱うリソース・機能 • リクエスト HTTPメソッド、パス、ボディ、etc.) • レスポンス (ステータスコード、ボディ、etc.) • 認証・認可（誰が・何をできる） • エラー・例外ケースの扱い • 非機能要件 Security、Performance、etc.)
33. APIコントラクト • API提供・利用者間の合意した契約であり、APIがデータや機能をどう提供するかを文章化 • リクエストやレスポンスの構造やデータ型、ステータスコードなどが含まれる • API仕様の記述形式は、自由記述ではなく、機械可読な標準仕様形式が推奨される：OpenAPI仕 様、JSON Schema、GraphQL Schema、など API コントラクト API 提供者 API 利用者 APIリクエスト 参照 参照 APIレスポンス OpenAPI
34. API仕様記述フォーマットの採用状況 2023年段階で最も広く採用されているAPI仕様フォーマットはJSON Schemaで、次いで Swagger/OpenAPI 2.0、およびOpenAPI 3.x 参考資料 2023 State of the API report https://voyager.postman.com/pdf/2023-state-of-the-api-report-postman.pdf
35. JSON Schema - JSONデータ構造記述のための標準仕様 API仕様そのものというよりも、 API仕様の中の「データ構造部分」を担う要素として使われることが一般的。例え ば、REST APIのリクエスト・レスポンスにおけるデータバリデーションや型チェックを行う目的で使用されること が多く、OpenAPI仕様などの仕様と組み合わせて利用されている JSON Schemaの構文 • type: データ型（string、number、object、array、など） • properties: オブジェクトの各プロパティとその型・制約 • required: 必須フィールドの指定 • format: 特定フォーマット（email, date-time など） • enum: 限定された値のリスト • minimum / maximum: 数値の範囲制限 { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "age": { "type": "integer", "minimum": 0 } }, "required": ["id", "name"] } JSON Schemaによるスキーマ定義例 JSON Schema公式リファレンス https://json-schema.org/understanding-json-schema/reference JSON Schema GitHubリポジトリ https://github.com/json-schema-org/json-schema-spec
36. OpenAPI  REST APIの標準仕様形式 OpenAPI（最新は2025年9月発表の3.2.0）は、RESTful APIのためのAPI記述形式で、HTTP API機能を人間 とコンピュータが理解できるようにするためのプログラム言語に依存しない仕様形式 記述形式：JSON、YAML info OpenAPI Specification 3.1 servers paths webhooks components security tags externalDocs
37. OpenAPI  REST APIの標準仕様形式 基本構成（OpenAPI 3.1準拠） • openapi: OpenAPIのバージョン（例: 3.1.0） • info: APIのタイトル、バージョン、ライセンス、説明などのメタ情報 • servers: APIのベースURLや環境を定義（開発、本番など） • paths: 各エンドポイントの定義と、使用する HTTPメソッド、リクエスト・レス ポンス構造 • webhooks: サーバーからクライアントへのコールバック（イベント駆動型通 信）を定義（3.1以降） • components: 共通して使われるスキーマやパラメーターなどの再利用可 能な定義群 • security: 認証や認可方式（例： APIキー、OAuth2など） • tags: エンドポイントを論理的なグループで分類するためのラベル • externalDocs: 追加の外部ドキュメントへのリンク（ APIの詳細な仕様のガ イドなど） ＊ 本ハンズオンでは OpenAPI3.0仕様を活用するが、上記構成の中で webhooks以外は OpenAPI3.0にも存在する JSON Schema形式 ID指定のユーザー情報取得 API GET /users/{id} のOpenAPI仕様定義 OpenAPI3.1 Specification https://github.com/OAI/OpenAPISpecification/blob/main/versions/3.1.0.md
38. API設計ベストプラクティスを学ぼう 主要なAPI設計ベストプラクティス • リソース指向設計 • データ設計 • 適切なHTTPステータスコード、エラーレスポンス • バージョニングの明示 • パフォーマンス観点 • セキュリティ観点 本セッションではこれらベストプラクティスの詳細について触れませんが、本資料の APPENDIX に主要なAPI設計プラクティスに関するスライドを載せています。興味 のある方はぜひご覧ください。
39. API開発における障壁 全体では時間と人手不足が主要な障壁。しかし、5000人以上開発者がいる大規模組織においてはAPI のデザインスキル不足がトップ 2023 State of the API Report https://voyager.postman.com/pdf/2023-state-of-the-api-report-postman.pdf #1 時間がない 43% #2 人員不足 37% #3 API設計スキル不足 32% #4 ドキュメント不足 #5 知識不足 #6 予算不足 #7 管理するAPIが多すぎる #8 組織の賛同や支持 #9 サポートAPIの発見が困難 #10 ツール不足 2023年 Postman State of API report
40. そもそも良いAPIとは？
41. 良いAPIとは? Good APIs tend to offer clarity (of purpose, design, and context), flexibility (ability to be adapted to different use cases), power (completeness of the solution offered), hackability (ability to pick up quickly through iteration and experimentation), and documentation. In a book - Designing Web APIs - building that developers love by Chris Messina, developer experience lead at Uber (意訳) 通常、良いAPIは、目的・設計・文脈が明確であり、 柔軟性があり、提供されるソリューションに完全性があり、 すぐに理解できて、ドキュメントが提供されています。
42. 良いAPIに求められる特性 - 変わらないもの 設計特性 • モジュール性 • 機械可読性 • 適応性 Adaptability) • 構成可能性 Composability) • 互換性 • ⋯ 利用者にとって必要な特性 • 利用者ニーズを満たす • 開発者体験が良い • 発見しやすい • 一貫性がある • 信頼性がある 本セッションでは設計特性につ いては特に触れません
43. 利用者にとって良いAPIの特性 良いAPI (プロダクト) 開発者体験が良い 発見しやすい 一貫性がある 信頼性がある 利用者ニーズを満たす 特性 APIドキュメント 開発者ポータル、サンドボックス環境 APIカタログ、マーケットプレイス APIガバナンス対策 コラボレーション環境・組織体制 APIテスト・テストコード APIコントラクト ライブラリ、SDK、サンプルコード APIセキュリティ対策 良いAPI実現のための要素
44. API設計の落とし穴 良いAPI (プロダクト) 開発者体験が良い 発見しやすい 一貫性がある 信頼性がある 利用者ニーズを満たす 特性 APIデザインガイドを守るっているからといって良いAPIをつくれるわけではない
45. API設計の落とし穴 • ユーザーニーズを後回しにする ◦ ガイドラインやパターンを守る＝ユーザビリティ保証ではない • 使いやすさを後回しにする ◦ モックやプロトタイプでの仮説検証が不足 • 運用・セキュリティ視点が希薄 ◦ 規模拡大、バージョン増加、権限追加といった 拡張・拡大・成長への備えがない ❌ ガイドライン準拠だけど使われないAPIになる恐れがある
46. 正攻法に立ち返るヒント • 利用者ニーズをまず考える ◦ ユースケース → API設計 → ガイドライン適用 の順に行う • 使いやすさを検証する ◦ プロトタイプやモックを早期公開し、開発者体験のフィードバックループを作る • 非機能要件は設計段階で ◦ セキュリティ・パフォーマンスなど非機能要件を設計フェーズで盛り込む ◦ シフトレフト
47. APIファーストの世界 https://api-first-world.com/ja/ 参考 APIファースト - 良いAPIを作るための1つの考え方
48. APIファーストとは？ • APIに対する位置づけ、考え方 ◦ APIはプロダクト（主要ソフトウェア構成要素、主要ビジネスアセット） ◦ APIがビジネスにもたらす価値に焦点を当てる ◦ API中心：内外サービスをAPIを通じて活用しビルディングブロックで構築 • API開発モデル ◦ APIを最優先に開発（APIを後回しにしない） ◦ コードを書く前にAPIを設計・構築 • APIファースト採用のために必要な取り組み ◦ APIライフサイクルを理解しライフサイクル全体で取り組む ◦ APIの継続的な保守・運用のためのチーム体制を構築する APIFirst Guide https://www.postman.com/api-first/ 参考
49. API設計ファースト開発モデル • ゴール: 利用者のニーズを満たした機械判読可能なAPIコントラクトの完成 • 理想の開発モデル ⇒ API設計ファースト：コードを書く前にAPIを設計・構築し、モック、ドキュメント、 テストも作成し、フィードバックループを通じて設計内容を洗練化 • ただし、必ずしも設計ファーストでなければならいというわけではない APIコントラクトの作 成 モック作成 テスト作成 ドキュメント作成 API実装 コーディング テスト API統合 フィードバック TDD TDD 仮説検証 API設計 API設計ファースト開発プロセス 参考
50. さまざまな開発アプローチ APIファーストでは、利用者のニーズを満たす機械判読可能な API コントラクトの完成を目標とし、その理想 的なアプローチとして API設計ファースト を掲げている。ただし、その到達までのプロセスは一つに限定さ れず、状況に応じてさまざまなパスを許容する柔軟性も備えている。 参考資料 APIコントラクト プロトタイプファースト 先にコレクション、モックなど APIの プロトタイプを作成 コードファースト API のコーディングを優先 プロキシファースト プロキシ経由で既存の APIへのトラフィック に基づきコレクションを作成 OpenAPI、Postmanコレクションなど 設計ファースト API の設計を優先し、先に API仕様を作成 フィードバックループを通じて仕様を作成 ・洗練化 プロトタイプとしてコレクションを作成 Annotationを元に仕様を自動生成 プロキシを通じて実際の APIへの トラフィックを元に仕様を自動生成
51. Postmanを活用したAPIファースト開発アプローチについて学べる書籍 https://amzn.asia/d/0SdTMlO
52. APIテストの実践ポイント
53. Web APIテストの目的 APIテストは、インターフェースの品質、信頼性、セキュリティを確保するために行います 機能要件 • APIコントラクトテスト: APIがコントラクト通りの仕様 で実装されているか • 機能テスト: APIが期待通りの振る舞いであるかどう か 非機能要件 • セキュリティテスト: APIを通じたやりとりがセキュア か • パフォーマンステスト: APIのパフォーマンスに問題 がないか
54. 機能面のチェック項目 • コントラクト • CRUD操作の一貫性・冪等性 • APIバージョンの独立性・互換性 • エラーハンドリング
55. セキュリティ面のチェック項目 • 認証・認可設定 • 無制限のリソース消費 • データの漏洩 / 過剰なデータ露出防止 • 入力データのバリデーション（インジェクション / XSS防止） • HTTPヘッダーのセキュリティ設定
56. パフォーマンスのチェック項目 • 高負荷時の性能 • 想定される高負荷のパターンにおいて、レイテンシーやエラーレートが許容範囲内か • 長期安定性 • 長期間の運用で異常なリソース消費（メモリリークやCPU使用率の異常値）がないか • スケーラビリティ • サーバーの数などAPIのリソース増減に応じてパフォーマンスが期待通りに変動（水平スケールなど）するか • リソース効率 • CPU、メモリ、ディスクI/O、ネットワーク帯域などAPIサーバのリソースに過剰、無駄な消費がないか • APIの限界値 • APIが限界値（最大同時接続数、など）と限界値を超えたときの挙動について確認がとれているか
57. Web APIテスト共通で心がけたいこと • シフトレフトを心がける（早い時期からテスト実施） • APIドキュメントを整備する • APIライフサイクルにわたりテストを実施する（開発時だけではない） • 優先順位をつけてテストを自動化する • テストケースを継続的にアップデートする
58. Web APIテスト実施の現状 • 回答者のうち6割以上が機能テスト と統合テスト を実施、45%がパフォーマンステスト を実施 • セキュリティテスト は37%で、APIのセキュリティ脅威が増加する中、この数値は衝撃的に低い 2024 Postman state of API report - Most common API testing practices https://www.postman.com/state-of-api/2024/api-production/ 2024年 Postman State of API report
59. 組織にとって最も懸念されるAPIセキュリティリスク 組織にとって最も懸念される API セキュリティリスクについて、 最も多く挙げられたのは 「不適切な認証・認可、 またはアクセス制御」 で、他のリスクと大きく差をつけている 2023年 Postman State of API report 2023 Postman state of API report - Greatest Security Risks https://voyager.postman.com/pdf/2023-state-of-the-api-report-postman.pdf
60. 認証・認可設定 認証とは、ユーザーが「誰であるか」を確認するプロセスであり、 認可はユーザーが「何を許可されているか」 を 決定するプロセス。APIテストではこの両観点で適切に実装されているかを確認する 認証の確認ポイント（誰であるか？） • 認証なしのアクセス試行 : 認証が必要なエンドポイントに対して、トークンなしのリ クエストが拒否されるか • トークンの有効期限の確認: トークンが適切に期限切れとなり、期限切れ後のア クセスが拒否されるか 認可の確認ポイント（何を許可されているか？） • オブジェクトレベルの認可: 他のユーザーが所有するリソースにはアクセスできな い（403 Forbiddenエラーが返る、など）ようになっているか • 機能レベルの認可: ユーザーの役割（例: 管理者、一般ユーザー）に応じて、アク セス可能なエンドポイントや許可されている操作（例: 他人のデータの削除）が制 限されているか
61. OWASP API Security Top 10 2023 • API12023 オブジェクトレベルの認可の不備 BOLA • API22023 認証の不備 • API32023 オブジェクトプロパティレベルの認可の不備 • API42023 無制限のリソース消費 • API52023 機能レベルの認可の不備 • API62023 機密性の高いビジネスフローへの無制限なアクセス • API72023 サーバーサイドリクエストフォージェリ SSRF • API82023 セキュリティ設定ミス • API92023 不適切なインベントリ管理 • API102023 安全でないAPIの利用 OWASP API Security Top 10 2023 https://owasp.org/www-project-api-security/
62. OWASP API Security Top 10 2023 • API12023 オブジェクトレベルの認可の不備 BOLA • API22023 認証の不備 • API32023 オブジェクトプロパティレベルの認可の不備 • API42023 無制限のリソース消費 • API52023 機能レベルの認可の不備 • API62023 機密性の高いビジネスフローへの無制限なアクセス • API72023 サーバーサイドリクエストフォージェリ SSRF • API82023 セキュリティ設定ミス • API92023 不適切なインベントリ管理 • API102023 安全でないAPIの利用 OWASP API Security Top 10 2023 https://owasp.org/www-project-api-security/
63. 特に認可制御は攻撃リスクが高い オブジェクトレベルの認可の不備 BOLAのイメージ 機能レベルの認可の不備 BFLAのイメージ • 認可制御はアプリロジックに依存する部分が大きく、適切な設計・実装をしないと、権限管理の不備が発 生しやすい ◦ 認可バイパスや権限昇格のリスク（管理者しか見れないものが見れてしまう） ◦ 認可ロジックがアプリケーションコード内に分散しやすく、一貫性がなくなる恐れあり • APIテストでは認可制御のチェックは慎重に ◦ 認可が適切に機能するかどうかは、テストが欠かせない
64. • リリース直前にしかセキュリティチェックを行われない • 脆弱性管理やセキュリティ要件の定期的な見直しが行われない • 一部の専門家だけの責任になっている（セキュリティは別チームの仕事） • 仕様や設計にセキュリティ視点が含まれていない • テスト範囲が偏っている（機能面は厚いがセキュリティ面のテストが弱い） セキュリティの対応・テストにおける典型的な失敗パターン 担い手・チェックポイントの集中 ❌ セキュリティを1カ所（あるいは後工程）に集めると、抜け漏れ・遅れ・属人化が 発生しやすくなり、システム全体のリスクが増大する
65. 󰢏 セキュリティは点ではなく線で考える • セキュリティをDevOpsプロセスの点ではなく線として設計・実装・運用の中に分散 配置させる（分散: セキュリティの担い手、チェックポイント） • 継続的にまわすことを考える フェーズ 主要なセキュリティ対策（目的） 設計 脅威モデリング、仕様の明文化（そもそも脆弱な仕様を作らない） 開発 セキュアコーディング、 SAST（開発段階で問題を埋め込まない） テスト セキュリティ面のテスト、コントラクトテスト （仕様違反、脆弱な実装、不具合を早期に発見） 本番運用 WAF/監視/トラフィック制御（攻撃や不正操作をブロック＆検知） 保守 SBOM / 脆弱性管理、定期的セキュリティ要件の見直し
66. 大ゴケを阻止するためのヒント • APIテストは、インターフェースの品質、信頼性、セキュリティを確保するために行う • 特にセキュリティ（中でも認証・認可）は重点的に行う • セキュリティのチェックは点ではなく線で考える
67. APIドキュメンテーションの実践ポイント
68. 2023 State of the API Report https://www.postman.com/state-of-api/executing-on-apis/#obstacles-to-consuming-apis #1 ドキュメント不足 52% #2 APIの発見が困難 32% #3 時間がない28% #4 知識不足26% #5 予算不足23% #6 人員不足22% #7 APIの再利用が困難 19% API利用における障壁
69. APIドキュメントそのものに対する課題も多い • 開発者体験が低いフォーマット ◦ 独自形式、機械が読めない、相互運用性がない・・・ • 不十分な説明 ◦ 機能説明、認証認可方式、クイックスタートがない • 一貫性のない命名規則、フォーマット ◦ 命名規則が一貫していないため、混乱を招く • エラーハンドリングの欠如 ◦ エラーメッセージ、ステータスコードの説明 • アップデート ◦ 古い情報、更新されていない情報 • 不十分な使用例 / サンプル ◦ どのように利用すればいいか分からない
70. APIドキュメントとAPI仕様 APIドキュメントとAPI仕様は実際には違うものであるが、現場では API 仕様＝API ドキュメント のように 一括りで呼ばれることが少なくない API仕様 Spec APIドキュメント 目的 エンドポイント・リクエスト・レスポンスの構造・デザ インを定義し、ツール連携や自動化の土台にする 仕様を元に、開発者・利用者が実装・運用できるよう分か りやすく説明した文書（取扱説明書） 形式 OpenAPI / AsyncAPI / GraphQL schema / gRPC proto / Postmanコレクションなど標準化さ れ、機械可読な形式 Markdown、Wiki・CMSサイト形式、仕様を元にツール ReDoc、Stoplight、Postmanなど)で生成されたページ 内容 パス・メソッド・スキーマ・ステータスコード・例外な ど、インターフェースの内容 概要、クイックスタート、APIリファレンス、チュートリアル、 SDK、変更履歴、SLA、など
71. API仕様例 - OpenAPI https://raw.githubusercontent.com/freee/freee-api-schema/master/v2020_06_15/open-api-3/api-schema.json OpenAPI Spec Swagger Editor表示
72. APIドキュメント例 - freee API例 https://developer.freee.co.jp/reference 認可設定 APIの共通仕様 FAQ
73. APIドリフト問題（実装と記述とのズレ） • API仕様・ドキュメントと運用中の API実装の間に不一致で生じる問題 • API仕様・ドキュメントの更新不足、コミュニケーション不足、 APIの設計・開発・運用プロセスにおけるガバ ナンス不足などが主な原因 • 記述にないAPI (シャドーAPI は、セキュリティテストや監視の対象外となり攻撃者にとって絶好のター ゲットとなる In our analysis of hundreds of leading APis from some of the largest providers in the field, we discovered that almost 30% of published APIs did not match the APIs in operational use. 公開されているAPIの約30%が、公開されているAPI記述と一致しない 動作をしている The challenges of API Drift - most production APIs don't match their specs Aug 2024, APIContext社) https://apicontext.com/resources/api-drift-white-paper/
74. 実装とのズレを防ぐためのポイント • 何が信頼できる単一情報源/SSOTかを見極める（API仕様やソースコード） • 仕様 /ドキュメントの生成はできるだけ自動化し、実装との間にズレがないことを自動検証する 自動生成 • （デザインファーストの場合）仕様からSDK / スタブ、テストコードを生成 • （コードファーストの場合）コードやアノテーションからの仕様を生成 自動検証 • 本番環境のコントラクトテスト（CI/CD経由、モニター経由で） • メインと開発ブランチ間の仕様の差分チェック（PRごとにCI経由で） • APIゲートウェイ、WAF、プロキシでのAPIスキーマ検証、シャドーAPIの検出 ※ SSOT  Single Source of Truth
75. まとめ
76. まとめ AI時代に求められる良いAPIのつくりかたの話をしました • 一度作って終わりではなく継続的に使われることを前提に、ライフサイクル全体で考える • 使いやすくなければ、APIの価値は発揮されない • AIReady APIとは、人にもAIにもやさしく、安全かつ継続的に利用できるAPI • AIにやさしいAPIは、本質的に人間にもやさしい • 良いAPIを、ちゃんと作ろう • AI時代だからこそ、APIの基本がより厳しく問われる
77. Q&A
78. ご清聴いただき、ありがとうございました。
79. APPENDIX
80. 主要API設計ベストプラクティス • リソース指向設計 • データ設計 • 適切なHTTPステータスコード、エラーレスポンス • バージョニングの明示 • パフォーマンス観点 • セキュリティ観点
81. API設計: リソース指向設計 Web API設計のアプローチの 1つであり、REST APIの設計において広く採用されている。この設計スタイルで は、各リソースを一意に識別し、 HTTPメソッドを用いてアクセスする方法に焦点を当てる 良い例 悪い例 リソースを適切に表現 • GET /users（全ユーザーを取得） • POST /users（ユーザー新規作成） • GET /users/{id}（ユーザー情報取得） • PUT /users/{id}（ユーザー情報更新） • DELETE /users/{id}（ユーザー削除） 動詞を含むパターン • GET /getUsers • POST /createUser • DELETE /removeUser パスパラメーター例: • /users/{userId}（特定のユーザー） クエリパラメーター例 • users?status=active （フィルタ） • /users?role=admin&sort=created_at （フィルタ・ソート） • 名前でリソース名を表現 ◦ ユーザー: /users、特定ユーザー: /users/{id} ◦ ユーザーの全注文履歴: /users/{id}/orders ◦ 特定の注文: /users/{id}/orders/{orderID • HTTPメソッドでリソース操作を表現 ◦ GET リソースの取得 ◦ POST リソースの新規作成 ◦ PUT リソースの更新（全体） ◦ PATCH リソースの部分的な更新 • パラメーターの使い分け ◦ リソースを一意に表現 ⇒ パスパラメーター ◦ リソースを表さない ⇒クエリパラメーター
82. API設計: データ設計 • 明確で一貫性のある命名規則の採用 ◦ プロパティ名を一貫性のある命名規則で統一する。プロパティ 名はキャペルケース（camelCase）やスネークケース （snake_case）などが一般的に採用されている • データ型を明確に区別して使用する ◦ 明確な型(string, number, integer, boolean, array, object) を指定し、曖昧さを避ける • データ構造はできるだけシンプルに ◦ データ構造が複雑になりすぎるのを防ぎ、できるだけシンプル に保つことが推奨されます。ネストが発生する場合は、深くし すぎず、ネスト構造を減らすことが重要 REST APIでは、データのやり取りに JSONが標準的に使用される { "userId": 1234, "userName": "yamada" } キャメルケースの例 { "type": "object", "properties": { "username": { "type": "string", "minLength": 3, "maxLength": 30 }, "age": { "type": "integer", "minimum": 0, "maximum": 120 } } } データ型と値の範囲指定の例
83. API設計: 適切なステータスコード・エラーレスポンス • 適切なHTTPステータスコードの利用 ◦ 適切なHTTPステータスコードを使用し、クライア ントに明確な状態を伝える • 適切なエラーレスポンスの設計 ◦ 十分な情報提供： 利用者が適切にエラー処理が 行えるように適切なエラー情報を伝える（ただし、 個人情報やシステム内部情報は含めない） ◦ エラーメッセージの標準化： API全体で統一した エラーコード・フォーマットを使用する { "error": { "type": "rate_limit_error", "message": "Too many requests hit the API too quickly.Please retry after 10 seconds.", "code": "rate_limit", "retry_after": 10 } } エラーメッセージ例（ Stripe API Rate Limitエラー）
84. API設計: バージョニングの明示 APIは時間とともに進化し、機能追加や改善、既存の仕様変更が必要になる。そのため、 APIのバージョンを明 示的に管理し、利用者に影響を与えずに新しいバージョンを提供するための仕組みが必要 バージョニング方式 例 URLバージョニング /v1/users クエリパラメーター /users?version=1 ヘッダーバージョニング Accept-Version: v1 ドメイン・サブドメイン https://v1.api.example.com よく使われるAPIバージョニング管理パターン バージョニング戦略 • メジャーバージョンアップ (互換性のない変更 / Breaking Change) ◦ 1.x → 2.x • マイナーバージョンアップ (後方互換性のある変更 ) ◦ 1.0  1.1
85. API設計: パフォーマンス観点 パフォーマンスはユーザー体験そのもの。 APIのパフォーマンスを最適化するための代表的な手法： • ページネーション（ページ分割） ◦ オフセット & リミット（大量データに弱い） ▪ 21件目から30件目を取得: GET /users?limit=10&offset=20 ◦ カーソルベース（Cursor、大規模向けで比較的高速） ▪ カーソル abc123の次のデータを取得: GET /users?cursor=abc123 • フィルタリング（データ転送量の削減） ◦ デフォルトレスポンスの軽量化 ◦ 必要なフィールドのみ返す • キャッシュ活用 ◦ 一度取得したデータを一時的に保存し再利用することで、システムの負荷を軽減と、レスポンス時間を短縮 ◦ ２つのキャッシュアプローチ ▪ キャッシュヘッダーの活用（クライアント側キャッシュ） : Cache-Control や ETag を利用し、不要なリクエスト を削減して効率化する ▪ サーバー側キャッシュ : 頻繁にアクセスされるデータをメモリ、外部キャッシュサービス、CDNなどに保存し、レ スポンスを高速化する
86. API設計: セキュリティ観点 • 認証・認可設定 • 認証（ユーザーが「誰であるか」）と、認可（ユーザーが「何を許可されているか」）を確認するプロセスを適切に設計す る • 無制限のリソース消費 • 各APIリクエストごとの過剰なリソース消費を抑えるための設定 • レートリミット、スロットリング • データの漏洩 / 過剰なデータ露出防止 • APIを通じたデータの漏洩や過剰なデータ露出がないようにするための対策 • クエリ文字列 / URLパス、APIレスポンス、エラーメッセージ • 入力データのバリデーション（インジェクション / XSS防止） • HTTPヘッダーのセキュリティ設定 • 業界で確立された推奨セキュリティヘッダーを設定し、正しく機能しているかをテスト • OWASP API Security ガイドライン（＊）などを参考にする OWASP REST API Security CheatSheet https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html#security-headers
87. 機能面のチェック項目の補足資料 • コントラクト • CRUD操作の一貫性・冪等性 • APIバージョンの独立性・互換性 • エラーハンドリング
88. コントラクトテストとは？ • コントラクト = API提供者・利用者間で合意した契約 OpenAPI、GraphQL schema、protobuf ) • コントラクトテストは、 APIがコントラクト通りに振る舞うことを確認するテスト • API提供者はコード変更のたびにリグレッションテストとして、 API利用者にとっては利用している APIに変 更がないかなど定期的に検証していくのがよいとされている コントラクトテストでのチェック箇所例 • リクエスト・レスポンスのスキーマ整合性 • 型と値 • 必須パラメータ、フィールド • エンドポイントとHTTPメソッドの動作 • HTTPステータスコード API利用者・提供者によるコントラクトの利用イメージ
89. APIの冪等性 Idempotency) • 複数回リクエストを送信しても、結果が変わらないことの確認 • 冪等性が担保されることで、リトライ / 再送処理があったとしてもデータの不整合が防げる • 冪等性のあるメソッド： GET, PUT, DELETE, HEAD, OPTIONS ◦ POSTは冪等性キーIdenpotency-key)の活用することで冪等性をもたせることが可能 同一PUTリクエスト送信で冪等性のチェック 冪等性キーを活用して POSTリクエストの冪等性をチェック 参考: Build Resilient Systems with Idempotent APIs https://dev.to/karishmashukla/building-resilient-systems-with-idempotent-apis-5e5p
90. APIバージョンごとの独立性・互換性 複数のAPIバージョンがある場合、各バージョンが互いに影響を及ぼさず、バージョンごとに期待通りの動作で あることを確認 確認ポイント • 独立性: バージョンごとのエンドポイントが併存し て正しく動作するか • 後方互換性: 変更内容が後方互換性を保ち既 存クライアントに影響を与えないか（メジャー バージョンアップではない後方互換性が期待さ れている場合） APIバージョン管理パターン • URI ◦ /api/v1/user や /api/v2/user • クエリパラメータ ◦ /api/user?v=1 や /api/user?v=2 • HTTPヘッダ ◦ Accept: application/vnd.example.v1+json • ドメイン/サブドメイン ◦ v1.example.com や v2.example.com
91. エラーハンドリング • 不正リクエストや異常な入力、例外や障害シナリオに対して コントラクト通りのエラーレスポンスが返却され るか確認（コントラクトテスト） • タイムアウトやリトライ処理のような回復性機能 もユニット、インテグレーションテストで確認する Shopify API response status and error codes https://shopify.dev/docs/api/usage/response-codes
92. ネガティブテストもしっかりやる ポジティブテスト（正常系のテスト）は特に言わなくても多くの方が実施するが、 ネガティブテスト（異常系やエッジ ケースのテスト）は見落とされがち ネガティブテストの例 タイプ チェック項目 入力バリデーション（リクエスト本文、ヘッ ダー、パラメータ） • 不正なデータ型や形式 • 必須パラメータ不足 • 重複データ • 大量、極端に大きい文字列やファイルサイズ 認証・認可 • 無効なトークン • 不適切なリソースや権限でのアクセス データの漏洩 / 過剰なデータ露出 / セ キュリティヘッダ • SQLインジェクション、XSS • 不正なCORSリクエスト システムリソース制限 • 異常なリソース消費を生ずるリクエスト（ タイムアウト設定、一度に返却可能なレ コード数の確認など） • 高頻度なリクエスト（レートリミットの確認）
93. セキュリティ面のチェック項目の補足資料 • 認証・認可設定 • 無制限のリソース消費 • データの漏洩 / 過剰なデータ露出防止 • 入力データのバリデーション（インジェクション / XSS防止） • HTTPヘッダーのセキュリティ設定
94. 無制限のリソース消費 APIリクエストに伴うリソース消費が制限されていない場合、攻撃者によるリソースの過剰消費でサービス妨害 やコスト増加を引き起こす可能性がある（「 API42023  Unrestricted Resource Consumption （無制限のリ ソース消費）」）。この問題を防ぐために、 APIリクエストごとの消費リソース とAPIリクエストのレート制限 の2つの 観点で対策されているか確認するようにしましょう 消費リソースの制限 APIリクエストごと) • 各APIリクエストごとの過剰なリソース消費を抑えるための設定がされているか • タイムアウト設定、ペイロードサイズ、アップロードファイルサイズ、一回のAPIリクエストで実行可能な命令の数、返却 可能なレコード数、など レート制限 • 各エンドポイントに適切なリクエスト数の制限（例: 10リクエスト/秒）が設定されている • 制限を超えたらリクエストが適切に拒否される（HTTP 429 "Too Many Requests"など） レート制限にはAPI全体で固定時間枠ごとの全体リクエスト数を制限する方式、クライアントの IPアドレスやユーザー IDごとにリクエスト数を制限する方式 など様々な方式がある。 API Gatewayのようなレイヤーで一元的に制御するのが一般的
95. データの漏洩 / 過剰なデータ露出防止 APIを通じたデータの漏洩や過剰なデータ露出がないか必ず確認するようにしましょう • クエリ文字列 / URLパス: 機密情報（例: セッションID、APIキー） • APIレスポンス: 必要以上の情報（例 : 内部ID、システムメタデータなど） • エラーメッセージ: スタックトレースなど内部の手がかりとなる情報 検証方法: 大きく次の２種類のアプローチがあり、それぞれメリット、デメリッ トを持っているが、両方を実施するのが最も効果的 • 直接リクエスト/レスポンスを検証 • ログを検証 { "error": "Database connection failed", "details": "Unable to connect to MySQL server at db.internal.example.com:3306. Access denied for user 'api_user'." } 内部の手がかりとなる情報が含まれたエラーメッセージ
96. HTTPヘッダーのセキュリティ設定 業界で確立された推奨セキュリティヘッダーを設定し、テストでこれらが正しく機能しているかを確認 参考: OWASP REST API Security CheatSheet https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html#security-headers ヘッダー推奨設定 説明 CORS関連ヘッダ Access-Control-Allow-＊) CORSはブラウザが異なるオリジンからのリクエストを制御するための仕組み。許可するオリ ジンやメソッドを最小限に制限し、不要なアクセスを防ぐ Cache-Control: no-store ブラウザーによるキャッシュを指示するために使用されるヘッダー。レスポンスのキャッシュを 禁止し、機密情報の保存を防ぐ Content-Type コンテンツのMIMEタイプを指定。未指定だとブラウザが推測し、スニッフィング攻撃のリスク がある Strict-Transport-Security HSTS HTTPSのみの通信を強制し、盗聴・改ざん・誤った HTTPアクセスを防ぐ。 XContent-Type-Options: nosniff ファイルの内容に基づいた MIMEタイプの推測ではなく Content-Typeで宣言されている MIME タイプの使用をブラウザに指示するヘッダー。不正な実行を防ぐ XFrame-Options: DENY レスポンスを他のサイトにフレーム化できるかどうかを指定するヘッダー。他サイトへの埋め込 みを禁止し、クリックジャッキングを防ぐ。
97. パフォーマンスのチェック項目補足資料 • 高負荷時の性能 • 想定される高負荷のパターンにおいて、レイテンシーやエラーレートが許容範囲内か • 長期安定性 • 長期間の運用で異常なリソース消費（メモリリークやCPU使用率の異常値）がないか • スケーラビリティ • サーバーの数などAPIのリソース増減に応じてパフォーマンスが期待通りに変動（水平スケールなど）するか • リソース効率 • CPU、メモリ、ディスクI/O、ネットワーク帯域などAPIサーバのリソースに過剰、無駄な消費がないか • APIの限界値 • APIが限界値（最大同時接続数、など）と限界値を超えたときの挙動について確認がとれているか
98. パフォーマンスはユーザー体験である ソフトウェアやウェブアプリケーションのパフォーマンスはユーザーエクスペリエンスに直結してい るとても重要な要素 Web performance is user experience. As you design and develop a new site, youʼll consider many components of its user experience: layout, hierarchy, intuitiveness, ease of use, and more. Your siteʼs experience determines how much your audience trusts your brand, returns to your site, and shares it with others. Designing for performance, by Lara Callender Hogan, Dec 2014 https://www.oreilly.com/library/view/designing-for-performance/9781491903704/ https://designingforperformance.com/index.html
99. パフォーマンス計測のための 主要メトリクスと計測内容の例 メトリクス 計測内容 観点 レイテンシ 各APIの平均応答時間、95パーセンタイル （P95）、99パーセンタイル（P99）のレイテンシ が許容範囲内か ユーザー体験に直接影響を与える指標。平均レイテンシだけでな く、P95やP99といった負荷状況での性能を把握してボトルネック 解消のための指針として利用 スループット APIが1秒間に処理可能なリクエスト数（ RPS Requests Per Second） APIのスケーラビリティを測る指標。必要な RPSが達成できない場 合、インフラ拡張やコード最適化などの対策を検討 エラーレート 5xx系、4xx系のエラーレスポンス率 システムの不安定さを示す指標で、 5xxエラーはサーバーサイド の問題を示す。高負荷下でエラーレート（特に 5xx系）が急増して いないか確認 システムリソース 使用状況 APIサーバーのCPU使用率、メモリ消費量、ネッ トワーク帯域の使用状況 API処理の効率性や、ボトルネック特定のために利用
100. シナリオに応じた負荷増減をシミュレーションする シナリオに応じた負荷の増減をシュミレーションして、安定的に動作するかを確認する。単調な負荷では見えな い問題の発見ができる。ウォームアップの必要性、スケール速度など ランプアップ型 ピーク型 スパイク型 Postmanパフォーマンステスト機能で利用可能な負荷プロファイルの種類（固定以外）