Upgrade to Pro — share decks privately, control downloads, hide ads and more …

AI時代のAPIファースト設計 - AWSとPostmanで実践する品質とスピードの両立...

Sponsored · Ship Features Fearlessly Turn features on and off without deploys. Used by thousands of Ruby developers.

AI時代のAPIファースト設計 - AWSとPostmanで実践する品質とスピードの両立 / API Frirst in the age of AI

Presentation slides for トレノケートオンラインセミナー 20260209
Session title: AI時代のAPIファースト設計 - AWSとPostmanで実践する品質とスピードの両立
Date: 2026/02/09

Avatar for Yoichi Kawasaki

Yoichi Kawasaki

February 09, 2026
Tweet

More Decks by Yoichi Kawasaki

Other Decks in Technology

Transcript

  1. All rights reserved by Postman Inc AI時代のAPIファースト設計 ~ AWSとPostmanで実践する品質とスピードの両立 川崎庸市

    テクノロジーエバンジェリスト トレノケート オンラインセミナー 2026.02.09
  2. Web APIはこれまで以上に重要になっている APIは、システムと他のサービスやデータソースとの連携を可能にし、効率的なデータ処理とインタラク ションを実現するための基盤 @postman_japan オルタナティブ・ブログ / ITソリューション塾 / 【図解】コレ1枚でわかる

    APIエコノミー https://blogs.itmedia.co.jp/itsolutionjuku/2022/07/api_3.html AI導入の加速 AI技術は単体では完結せず、多くの異なるシステム、サービス、データソースと統合さ れる必要がある。下記は MCPを介したAIとの相互作用のイメージ APIエコノミーの拡大
  3. AIDLC AIDriven Development Lifecycle) AIDriven Development Lifecycle AIDLC Method Definition

    https://prod.d13rzhkk8cj2z0.amplifyapp.com/ AIを開発パートナーとして組み込み、設計から テスト・運用までの全工程を高速化・自動化す る次世代の開発プロセス • Inception: 構想フェーズ • Construction: 構築フェーズ • Operation: 運用フェーズ
  4. Spec-Driven Development SDD • SpecをSingle Source of Truth としコード・テスト・検証までを仕様中心で進める開発モデル •

    人はコードを直すのではなく、 Specを直す 人間 Architect / PO Spec Steering ファイル Rules/ Policies/OpenAPI Implementation AI Agent 実装 / テスト生成 Testing コード / テスト 定義・修正 Steering 生成 実行結果・ズレ ルール追加 ズレ報告 GitHub SpecKit の場合の流れ(Specify → Plan → Tasks → Implement) Specify 仕様の作成 Plan 実装計画の策 定 Tasks タスクの整理 Implement 実装 確認 確認 確認
  5. APIの品質をあげるために設計・開発フェーズで必要なもの 代表的なもの2つ 高品質なテストの早期用意 • コントラクトテスト、単体テスト、統合テスト、シナリ オテスト • エッジケースやエラーハンドリングの検証 • パフォーマンスやセキュリティテスト

    • リグレッションテストによる品質の維持 高品質なAPI仕様の早期用意 • フロントエンドとバックエンドの認識齟齬を防ぎ、 手戻りを削減 • 実装前のレビューやフィードバック • 早期段階でのセキュリティ問題の発見
  6. API設計とは? • APIがデータや機能をAPI利用者にどのように提供するかを決めるプロセス • このプロセスで決定した内容をAPI仕様(APIコントラクト) として文書化 • 良いAPI設計=「利用者のニーズを満たすこと」が目的に検討し、その結果をAPI仕様に反映 • 目的

    • ユースケース(誰が、何を、どう操作して、何を実 現できるか、etc.) • 利用条件 • 非機能要件 • APIが扱うリソース・機能 • リクエスト HTTPメソッド、パス、ボディ、etc.) • レスポンス (ステータスコード、ボディ、etc.) • 認証・認可(誰が・何をできる) • エラー・例外ケースの扱い • 非機能要件 Security、Performance、etc.)
  7. APIにおいてAPI仕様とは Single Source of Truth • API提供・利用者間の合意した契約であり、APIがデータや機能をどう提供するかを文章化 • リクエストやレスポンスの構造やデータ型、ステータスコードなどが含まれる •

    API仕様の記述形式は、自由記述ではなく、機械可読な標準仕様形式が推奨される:OpenAPI仕 様、JSON Schema、GraphQL Schema、など API コントラクト API 提供者 API 利用者 APIリクエスト 参照 参照 APIレスポンス OpenAPI
  8. APIの開発スピードを上げるために必要なもの 代表的なもの2つ 技術的な基盤 • CI/CDパイプラインの構築 • テスト・ビルド・デプロイの自動化 • モック作成やテスト環境の整備 •

    APIドキュメントの自動生成 開発プロセス • API設計ガイドラインの整備 • レビュープロセスの確立 • バージョン管理とブランチ戦略の確立 • 依存関係管理の効率化
  9. API開発の品質とスピードを両立するために必要なもの 高品質なテストの早期用意 • コントラクトテスト、単体テスト、統合テスト、シナリ オテスト • エッジケースやエラーハンドリングの検証 • パフォーマンスやセキュリティテスト •

    リグレッションテストによる品質の維持 技術的な基盤 • CI/CDパイプラインの構築 • テスト・ビルド・デプロイの自動化 • モック作成やテスト環境の整備 • APIドキュメントの自動生成 高品質なAPI仕様の早期用意 • フロントエンドとバックエンドの認識齟齬を防ぎ、 手戻りを削減 • 実装前のレビューやフィードバック • 早期段階でのセキュリティ問題の発見 開発プロセス • API設計ガイドラインの整備 • レビュープロセスの確立 • バージョン管理とブランチ戦略の確立 • 依存関係管理の効率化
  10. APIファーストとは? • APIに対する位置づけ、考え方 ◦ APIはプロダクト(主要ソフトウェア構成要素、主要ビジネスアセット) ◦ APIがビジネスにもたらす価値に焦点を当てる ◦ API中心:内外サービスをAPIを通じて活用しビルディングブロックで構築 •

    API開発モデル ◦ APIを最優先に開発(APIを後回しにしない) ◦ コードを書く前にAPIを設計・構築 • APIファースト採用のために必要な取り組み ◦ APIライフサイクルを理解しライフサイクル全体で取り組む ◦ APIの継続的な保守・運用のためのチーム体制を構築する APIFirst Guide https://www.postman.com/api-first/
  11. APIファースト開発モデル • ゴール: 利用者のニーズを満たした機械判読可能な APIコントラクト の完成 • コードを書く前にAPIを設計・構築し、モック、ドキュメント、テストも作成し、フィード バックループを通じて設計内容を洗練化 API設計

    テスト APIドキュメント 作成 モック作成 実装 コーディング 統合 テスト実行 監視実行 サーバー環境 Dev Stage Prod モック活用 テスト ドキュメント 活用 コードリポジトリ モックを元にレビューや フィードバックを受け 設計内容を洗練させる check-in デプロイ エンドポイント にテスト API開発環境
  12. さまざまな開発アプローチ APIファーストでは、利用者のニーズを満たす機械判読可能な API コントラクト の完成を目標とし、その理 想的なアプローチとして API設計ファースト を掲げている。ただし、その到達までのプロセスは一つに限定 されず、状況に応じてさまざまなパスを許容する柔軟性も備えている。 参考資料

    APIコントラクト プロトタイプファースト 先にコレクション、モックなど APIの プロトタイプを作成 コードファースト API のコーディングを優先 プロキシファースト プロキシ経由で既存の APIへのトラフィック に基づきコレクションを作成 OpenAPI、Postmanコレクションなど 設計ファースト API の設計を優先し、先に API仕様を作成 フィードバックループを通じて仕様を作成 ・洗練化 プロトタイプとしてコレクションを作成 Annotationを元に仕様を自動生成 プロキシを通じて実際の APIへの トラフィックを元に仕様を自動生成
  13. All rights reserved by Postman Inc Postman とは? 全世界4,000 万人以上のユーザーに使われている

    APIを構 築して利用するための API プラットフォームです。 APIのライフサイクル全般にわたり効率的なコラボレーション を通じて信頼性の高いAPIを実現します。
  14. APIライフサイクル全般での活動を支援 定義 設計 開発 テスト セキュリティ デプロイ 監視・観測 ビジネス システム

    Security ・・・ コード管理 システム設定 モック API コントラクト API仕様) API開発 リクエスト キャプチャ セキュリティ テスト 要件定義 Postman コレクション 生成 パフォーマンス テスト コントラクト テスト E2E テスト ソースコード 成果物 コミット 自動テスト APIサーバー Build/Deploy API Gateway Build/Deploy CI/CD ・・・ 配布 モニター アラート APM レポート APIカタログ API 開発ポータル トリガー 連携 トリガー ユーザー フィードバック フィードバックループ UIテスト テスト コラボレーション ドキュメント
  15. Postmanを活用したAPIファースト設計のステップ API で実現する ゴールの決定 API コントラクトを定 義 モックとテスト で仮説検証 API

    の文書化 要件 OpenAPI仕様 Postman コレクション ドキュメント モック (モックサーバー ) テスト インポート コレクションでAPI仕様作成、 プロトタイピング 外部でAPI仕様を作成 OpenAPI仕様 Spec Hub) 相互変換 可能 Spec Hubで API仕様作成
  16. REST APIサービス構成、代表的なパターン • API Gateway + Lambda ◦ マネージドAPI管理 +

    サーバーレス構成、小~中規模 ◦ リクエストベースの従量課金でコスト最適化 ◦ 高トラフィック時のコスト増 • API Gateway + ECS (on Fargate) ◦ マネージドAPI管理 + コンテナ構成、中~大規模 ◦ Lambda の制約回避(長時間実行/ファイル処理など)= 柔軟なAPI構成可能 ◦ Fargate のコスト(稼働時間に応じた料金発生)、コンテナ管理が必要 • ALB  ECS (on Fargate) / EKS ◦ API管理無し or 独自+コンテナ構成、中~大規模 ◦ gRPC / HTTP2シナリオ、高トラフィック時にコスト削減、柔軟なAPI構成可能 ◦ API独自管理 + コンテナ管理が必要。EKSの場合は特に柔軟性は高いものの学習コ ストも高い • Lambda Function URLs ◦ 最もシンプルな構成(Lambda 単体で API 提供可能)、小規模・内部用 ◦ 低コストでサーバレスのメリットを活かせる。認証機能が弱い(IAM のみ) Amazon API Gateway (マネージド API管理サービス) Lambda Function URLs (シンプルHTTPエンドポイント) ALB (高機能なL7バランサー)
  17. 監視・アラート (モニター) API設計 (Spec Hub) APIテスト API ドキュメント APIモック (モックサーバー)

    セキュリティ& ガバナンス APIカタログ APIネットワーク) コラボレーション • コントラクトテスト • 機能テスト • パフォーマンステスト • セキュリティテスト • シナリオテスト • リグレッションテスト 手動 or 自動 (継続) 実行 API仕様ファイル OpenAPI AWS Postman 監視・観測 テスト APIデプロイ APIサービスでのPostman x AWS 連携イメージ • Postmanで高品質なAPI仕様を作成し、テストを通じてAPI品質担保 • AWSでAPIサービスをホストし、安定的かつスケーラブルに運用 APIシステム 参照 CI/CD IaC 良いAPIの実現
  18. 監視・アラート (モニター) API設計 (Spec Hub) APIテスト API ドキュメント APIモック (モックサーバー)

    セキュリティ& ガバナンス APIカタログ APIネットワーク) コラボレーション • コントラクトテスト • 機能テスト • パフォーマンステスト • セキュリティテスト • シナリオテスト • リグレッションテスト 手動 or 自動 (継続) 実行 API仕様ファイル OpenAPI AWS Postman 監視・観測 テスト APIデプロイ APIサービスでのPostman x AWS 連携イメージ • Postmanで高品質なAPI仕様を作成し、テストを通じてAPI品質担保 • AWSでAPIサービスをホストし、安定的かつスケーラブルに運用 APIシステム 参照 CI/CD IaC 良いAPIの実現
  19. コレクションとは? コレクションは、実行可能な関連APIリクエスト(群)の集合です。コレクション単位で(もしくはコレクションに 関連付けて)モックサーバー、モニター、テストスイートなど主要なPostman機能が利用できます コレクション APIリクエスト テスト サンプル APIリクエスト テスト サンプル

    APIリクエスト テスト サンプル コレクションでできる主なこと • 複数APIリクエスト、関連レスポンス、テストの定義 • ワークフロー定義(リクエスト呼び出しのシーケンス) • リクエスト・テスト実行の自動化(コレクションランナー活用) • コレクション単位の文書化 • モックサーバー利用(コレクション単位) • モニター利用(コレクション単位) • チームメイトや利用者とのコラボレーション ◦ フォーク(Fork) ◦ プルリクエスト ◦ コメント 他にもいろんなことができます @postman_japan
  20. モックサーバーでコレクションを元にモックAPIを作成 • モックサーバーはクラウドに作成され専用URLが発行される • API 実装との依存関係が分離され、他のチームの作業から独立して作業を進めることができる コレクション APIリクエスト設定1 GET /path1

    サンプル1 APIリクエスト設定2 POST /path2 サンプル2 APIリクエスト設定3 PUT /path3 サンプル3 リクエスト GET /path1 リクエスト POST /path2 リクエスト PUT /path3 Postmanモックサーバー https://<your-mock-subdomain>.mock.pstmn.io サンプル 1のレスポンスを返却 サンプル 2のレスポンスを返却 サンプル 3のレスポンスを返却
  21. コレクションの中のAPIリクエストでテストを構成 • 各APIリクエストに変数とスクリプトでテストコードの記述が可能 • 複数のAPIリクエストを組み合わせてシナリオテスト、E2Eテストも作れる コレクション APIリクエスト① テスト サンプル APIリクエスト②

    テスト サンプル APIリクエスト③ テスト サンプル 複数リクエストで構成されたシナリオテストが可能 Request ① POST /regist Request ② GET /get Request ③ POST /unregist スクリプト @postman_japan
  22. 人間 Architect / PO Spec Steering ファイル Rules/ Policies/OpenAPI AI

    Agent 実装 / テスト生成 コード / テスト 定義・修正 Steering 生成 実行結果・ズレ ルール追加 ズレ報告 OpenAPI仕様 Postman コレクション 生成 モックAPI テスト ドキュメント フィードバック ループ 仮説検証・フィードバックループを通じた API仕様品質向上 SDDにおけるAPI仕様の品質向上プロセス
  23. 監視・アラート (モニター) API設計 (Spec Hub) APIテスト API ドキュメント APIモック (モックサーバー)

    セキュリティ& ガバナンス APIカタログ APIネットワーク) コラボレーション • コントラクトテスト • 機能テスト • パフォーマンステスト • セキュリティテスト • シナリオテスト • リグレッションテスト 手動 or 自動 (継続) 実行 API仕様ファイル OpenAPI AWS Postman 監視・観測 テスト APIデプロイ APIサービスでのPostman x AWS 連携イメージ • Postmanで高品質なAPI仕様を作成し、テストを通じてAPI品質担保 • AWSでAPIサービスをホストし、安定的かつスケーラブルに運用 APIシステム 参照 CI/CD IaC 良いAPIの実現
  24. OpenAPIでAPIスキーマを一元管理したい理由 OpenAPIでAPIスキーマを一元管理したい理由 • APIドリフトの防止 ◦ API仕様と実際のAPI Gateway側の乖離防止 • OpenAPI/Swaggerエコシステム ◦

    OpenAPIでAPIスキーマを定義している人が多い ◦ ドキュメントやモック自動生成などOpenAPIエコシステム活用が可能 • バリデーション用スキーマとして活用 ◦ OpenAPIでAPI Gatewayのバリデーションスキーマも一括で管理できる 関連付け APIエンドポイント 関連例ソース
  25. OpenAPIでAPIスキーマ管理 - 標準OpenAPIをインポート • API GatewayはOpenAPI仕様のインポート・エクスポート機能をサポート • この標準インポート機能で OpenAPIをAPI Gatewayに取り込みAPIスキーマを作成する

    インポート しかし、標準のOpenAPIをそのままインポートする方式では、 API GatewayのAPIエン ドポイントとAWSリソース(lambdaなど)との関連付けがされない 関連付けされない
  26. OpenAPIでAPIスキーマ管理 - 現実的な方法 現実的なOpenAPIでのAPIスキーマとAWSのAPI関連リソースの管理手法として次の選択肢がある 選択肢 判定 説明 OpenAPIにAPI Gateway拡張 設定を追加して管理

    △ OpenAPI にAPI Gateway用拡張のx-amazon-apigateway-*を定義 する(OpenAPIに拡張定義が含まれてしまう) OpenAPIとCloudFormationで 管理 △ OpenAPI の中で API Gateway用拡張の x-amazon-apigateway-integration を定義する必要がある OpenAPIとAWS CDKで管理 ◯ スキーマ用のOpenAPIをピュアに保ちつつAWSリソース定義・構築用の CDKで完全に分離した管理が可能 AWS CDK APIスキーマ生成 参照 関連付け
  27. 監視・アラート (モニター) API設計 (Spec Hub) APIテスト API ドキュメント APIモック (モックサーバー)

    セキュリティ& ガバナンス APIカタログ APIネットワーク) コラボレーション • コントラクトテスト • 機能テスト • パフォーマンステスト • セキュリティテスト • シナリオテスト • リグレッションテスト 手動 or 自動 (継続) 実行 API仕様ファイル OpenAPI AWS Postman 監視・観測 テスト APIデプロイ APIサービスでのPostman x AWS 連携イメージ • Postmanで高品質なAPI仕様を作成し、テストを通じてAPI品質担保 • AWSでAPIサービスをホストし、安定的かつスケーラブルに運用 APIシステム 参照 CI/CD IaC 良いAPIの実現
  28. APIシステムは複雑 UI JavaScript Gateway Item API Search API Document API

    Item Service Search Service Document Service Item DB Search DB Document Storage UI/JS API DB Externa Servicel APIシステムは複数要素で構成 • 複数レイヤ(層)で構成 • 複数コンポーネントで構成 • 外部サービスも利用 • エンドユーザーは複数のAPIを組 み合わせて利用 品質を担保するには質の高いテストが 必要となる @postman_japan
  29. Postmanを活用したAPIテストのカバーエリア • UIテスト • E2Eテスト • リグレッションテスト • シナリオテスト •

    インテグレーションテスト • コントラクトテスト • ユニットテスト • セキュリティテスト • ユーザビリティテスト • パフォーマンステスト 機能要件テスト 非機能要件テスト E2E Integration API Unit コスト 実行時間 不確実要素 テスト数 テストのピラミッド テスト @postman_japan * APIのユーザービリティテスト はモックを通じて実施可能
  30. Postmanの柔軟なテストのしくみ テストスクリプト • 各APIリクエストにスクリプト( JavaScript)の記述ができる • リクエスト送信前 (pre-request) とレスポンス受信後(post-response)のフェーズで実行可能 •

    各リクエストには複数のテストを登録でき、それぞれに「合格」「失敗」の結果が出る • Mochaベースのテストフレームワークで、 AssertionライブラリとしてChai.js利用可能 • ローコード支援機能としてコードスニペットや AIアシスタント Postbot)の利用が可能 @postman_japan スクリプト 実行フェーズ テスト結果
  31. Postmanの柔軟なテストのしくみ テストスクリプト @postman_japan // ステータスコードが 200であることを確認 pm.test("Status code is 200",

    function () { pm.response.to.have.status(200); }); // レスポンスが JSONであることを確認 pm.test("Response is in JSON format", function () { pm.response.to.be.json; }); // レスポンスのボディが期待通りの構造と値を持っていることを確認 pm.test("Response has expected contract", function () { const jsonData = pm.response.json(); // idフィールドが数値で値が 1であることを確認 pm.expect(jsonData).to.have.property("id", 1); pm.expect(jsonData.id).to.be.a("number"); // nameフィールドが文字列で "Taro"であることを確認 pm.expect(jsonData).to.have.property("name", "Taro"); pm.expect(jsonData.name).to.be.a("string"); // emailフィールドが文字列で "[email protected]"であることを確認 pm.expect(jsonData).to.have.property("email", "[email protected]"); pm.expect(jsonData.email).to.be.a("string"); }); コントラクトテスト 認可テスト(ユーザーの権限確認) // 不正なトークンを設定 // ヘッダー Authorization: 'Bearer invalidToken' pm.test("Forbidden Check: Should return 403", function () {  // 403 Forbidden エラーチェック pm.expect(response.code).to.eql(403); }); 認証テスト(ユーザーの確認) // 認証が必要なエンドポイントに対して認証トークンなしで送信 pm.test("Unauthorized Check: Should return 401", function () { // 401 Unauthorized エラーチェック pm.expect(response.code).to.eql(401); });
  32. Postmanの柔軟なテストのしくみ テストスクリプト 複数のリクエストを組み合わせてシナリオテスト、 E2Eテストも作れる コレクション APIリクエスト① テスト サンプル APIリクエスト② テスト

    サンプル APIリクエスト③ テスト サンプル 複数リクエストで構成されたシナリオテストが可能 Request ① POST /regist Request ② GET /get Request ③ POST /unregist スクリプト @postman_japan
  33. Postmanで継続的に API 品質をチェックする仕組み Postman CLI & CI/CD PostmanはコレクションはPostman CLI (コマンドラインインターフェース

    )から実行可能。これを CI/CDに組み 込むことで継続的な APIテストの実行が可能となる # Postmanにログイン postman login --with-api-key {{postman-api-key}} # コレクションのテスト実行 postman collection run {{collection-ID}} # API定義に対してセキュリティ・ガバナンスチェック postman api lint {{api-definition-ID}} Postman CLIでのcollection run実行イメージ GitHub ActionsでのPostmanテストの実行イメージ
  34. Kiro Power for Postman KiroでAIがPostman(API開発・テストツール)の専門知識や機能を利用できるようにする拡張機能( Power) Kiro PowerでPostmanで検索してインストール Kiro Power

    for Postmanをインストールすると、次の2つ が自動的に設定される • Postmanリモート MCP サーバー ◦ Postman上の仕様やテストデータを MCP経由で操 作・管理可能 • API Postman Testing用のフック ◦ APIに関するコードや設定ファイルの変更をフック にPostmanコレクションのテストを実行