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

大失敗しないための Web API 開発レシピ / A recipe for not maki...

大失敗しないための Web API 開発レシピ / A recipe for not making a big failure on WebAPI development

Presentation slides for CData ナイト 2025 Summer
Session title: 大失敗しないための Web API 開発レシピ
Date: 2025/06/12

Avatar for Yoichi Kawasaki

Yoichi Kawasaki

June 12, 2025
Tweet

More Decks by Yoichi Kawasaki

Other Decks in Technology

Transcript

  1. 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
  2. APIデザインガイドを学ぶことは重要 • Vinay Sahni Enchant Co-Founder): Best Practices for a

    Pragmatic RESTful API • Zalando: Zalando RESTful APIガイドライン • Microsoft: RESTful Web API の設計 https://speakerdeck.com/nagix/xian-chang-deyi-li-tuapidezain
  3. 利用者にとって良いAPIの特性 良いAPI (プロダクト) 開発者体験が良い 発見しやすい 一貫性がある 信頼性がある 利用者ニーズを満たす 特性 APIドキュメント

    開発者ポータル、サンドボックス環境 APIカタログ、マーケットプレイス APIガバナンス対策 コラボレーション環境・組織体制 APIテスト・テストコード APIコントラクト ライブラリ、SDK、サンプルコード APIセキュリティ対策 良いAPI実現のための要素
  4. APIデザインの落とし穴 • ユーザーニーズを後回しにする ◦ ガイドラインやパターンを守る=ユーザビリティ保証ではない • 使いやすさを後回しにする ◦ モックやプロトタイプでの仮説検証が不足 •

    運用・セキュリティ視点が希薄 ◦ 規模拡大、バージョン増加、権限追加といった 拡張・拡大・成長への備えがない ❌ ガイドライン準拠だけど使われないAPIになる恐れがある
  5. 正攻法に立ち返るヒント • 利用者ニーズをまず考える ◦ ユースケース → API設計 → ガイドライン適用 の順に行う

    • 使いやすさを検証する ◦ プロトタイプやモックを早期公開し、開発者体験のフィードバックループを作る • 非機能要件は設計段階で ◦ セキュリティ・パフォーマンスなど非機能要件を設計フェーズで盛り込む ◦ シフトレフト
  6. APIはプロダクト API as a Product) • APIをプロダクトとしてAPI中心で考える ◦ APIは主要ソフトウェア構成要素、主要ビジネスアセット ◦

    APIがビジネスにもたらす価値に焦点を当てる ◦ 内外サービスをAPIを通じて活用しビルディングブロックで構築 • APIファースト採用のために必要な取り組み ◦ APIライフサイクル全体で取り組む ◦ APIの継続的な保守・運用のためのチーム体制を構築する @postman_japan APIファーストの世界 https://api-first-world.com/ja/ 参考
  7. APIファースト開発モデル • 焦点はAPIの設計(システムの抽象的な「契約」) • コードを書く前にAPIを設計・構築し、モック、ドキュメント、テストも作成 • 設計フェーズでフィードバックループを通じて設計内容を洗練化 API-first software development

    for modern organizations  https://medium.com/better-practices/api-first-software-development-for-modern-organizations-fdbfba9a66d3 API設計 テスト APIドキュメント 作成 モック作成 実装 コーディング 統合 テスト実行 監視実行 サーバー環境 Dev Stage Prod モック活用 テスト ドキュメント 活用 コードリポジトリ モックを元にレビューや フィードバックを受け 設計内容を洗練させる check-in デプロイ エンドポイント にテスト API開発環境 @postman_japan 参考
  8. Web APIテストの目的 APIテストは、インターフェースの品質、信頼性、セキュリティを確保するために行います 機能要件 • APIコントラクトテスト: APIがコントラクト通りの仕様 で実装されているか • 機能テスト:

    APIが期待通りの振る舞いであるかどう か 非機能要件 • セキュリティテスト: APIを通じたやりとりがセキュア か • パフォーマンステスト: APIのパフォーマンスに問題 がないか @postman_japan
  9. 認証・認可設定 認証とは、ユーザーが「誰であるか」を確認するプロセスであり、 認可はユーザーが「何を許可されているか」 を 決定するプロセス。APIテストではこの両観点で適切に実装されているかを確認する 認証の確認ポイント(誰であるか?) • 認証なしのアクセス試行 : 認証が必要なエンドポイントに対して、トークンなしのリ

    クエストが拒否されるか • トークンの有効期限の確認: トークンが適切に期限切れとなり、期限切れ後のア クセスが拒否されるか 認可の確認ポイント(何を許可されているか?) • オブジェクトレベルの認可: 他のユーザーが所有するリソースにはアクセスできな い(403 Forbiddenエラーが返る、など)ようになっているか • 機能レベルの認可: ユーザーの役割(例: 管理者、一般ユーザー)に応じて、アク セス可能なエンドポイントや許可されている操作(例: 他人のデータの削除)が制 限されているか
  10. 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/
  11. 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/
  12. 特に認可制御は攻撃リスクが高い @postman_japan オブジェクトレベルの認可の不備 BOLAのイメージ 機能レベルの認可の不備 BFLAのイメージ • 認可制御はアプリロジックに依存する部分が大きく、適切な設計・実装をしないと、権限管理の不備が発 生しやすい ◦

    認可バイパスや権限昇格のリスク(管理者しか見れないものが見れてしまう) ◦ 認可ロジックがアプリケーションコード内に分散しやすく、一貫性がなくなる恐れあり • APIテストでは認可制御のチェックは慎重に ◦ 認可が適切に機能するかどうかは、テストが欠かせない
  13. • リリース直前にしかセキュリティチェックを行われない • 脆弱性管理やセキュリティ要件の定期的な見直しが行われない • 一部の専門家だけの責任になっている(セキュリティは別チームの仕事) • 仕様や設計にセキュリティ視点が含まれていない • テスト範囲が偏っている(機能面は厚いがセキュリティ面のテストが弱い)

    @postman_japan セキュリティの対応・テストにおける典型的な失敗パターン 担い手・チェックポイントの集中 ❌ セキュリティを1カ所(あるいは後工程)に集めると、抜け漏れ・遅れ・属人化が 発生しやすくなり、システム全体のリスクが増大する
  14. 󰢏 セキュリティは点ではなく線で考える • セキュリティをDevOpsプロセスの点ではなく線として設計・実装・運用の中に分散 配置させる(分散: セキュリティの担い手、チェックポイント) • 継続的にまわすことを考える @postman_japan フェーズ

    主要なセキュリティ対策(目的) 設計 脅威モデリング、仕様の明文化(そもそも脆弱な仕様を作らない) 開発 セキュアコーディング、 SAST(開発段階で問題を埋め込まない) テスト セキュリティ面のテスト、コントラクトテスト (仕様違反、脆弱な実装、不具合を早期に発見) 本番運用 WAF/監視/トラフィック制御(攻撃や不正操作をブロック&検知) 保守 SBOM / 脆弱性管理、定期的セキュリティ要件の見直し
  15. 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利用における障壁 @postman_japan
  16. APIドキュメントそのものに対する課題も多い • 開発者体験が低いフォーマット ◦ 独自形式、機械が読めない、相互運用性がない・・・ • 不十分な説明 ◦ 機能説明、認証認可方式、クイックスタートがない •

    一貫性のない命名規則、フォーマット ◦ 命名規則が一貫していないため、混乱を招く • エラーハンドリングの欠如 ◦ エラーメッセージ、ステータスコードの説明 • アップデート ◦ 古い情報、更新されていない情報 • 不十分な使用例 / サンプル ◦ どのように利用すればいいか分からない @postman_japan
  17. 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、など 参考
  18. 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/
  19. 実装とのズレを防ぐためのポイント • 何が信頼できる単一情報源/SSOTかを見極める(API仕様やソースコード) • 仕様 /ドキュメントの生成はできるだけ自動化し、実装との間にズレがないことを自動検証する 自動生成 • (デザインファーストの場合)仕様からSDK /

    スタブ、テストコードを生成 • (コードファーストの場合)コードやアノテーションからの仕様を生成 自動検証 • 本番環境のコントラクトテスト(CI/CD経由、モニター経由で) • メインと開発ブランチ間の仕様の差分チェック(PRごとにCI経由で) • APIゲートウェイ、WAF、プロキシでのAPIスキーマ検証、シャドーAPIの検出 ※ SSOT  Single Source of Truth
  20. コラボレーション不足がもたらす組織的な問題 • 非標準・非一貫 ◦ バラバラのルール、ポリシー、成果物 ◦ → 横連携が難しい(サイロ化)、プロダクトの品質低下 • 重複

    ◦ 機能の重複、ドキュメンテーションの重複 (単一の信頼できる情報源/SSOTがない) ◦ → 保守コスト倍増、プロダクトの品質低下 • 知恵の未伝承 ◦ 組織ごとの知恵、決定・失敗の記録 ADR,ポストモーテム etc.)が他で活かされない ◦ → 属人化、非効率、技術負債増加 @postman_japan より多くのチーム・組織が関わることで この課題はさらに拡大する
  21. コラボレーションの仕組み導入の例 目的 例 ソースコード 変更を安全に共有 • バージョン管理システム導入 GitHub, GitLabなど) •

    変更はPRレビューを通す CI/CD 毎回自動チェック • PR に Lint/テスト/ビルドを必須化 GitHub Actions, CircleCI など) ドキュメント 単一の信頼できる情報源 • MarkdownをGitで管理、社内ポータルで管理 Confluence、Notionなど) プロジェクト管理 タスクの可視化 • 単一のバックログ  (Jira、Backlogなど)に集約しラベルで チーム・組織横断を表現 コミュニケーション 変更通知、即時相談 • 単一のコミュニケーションツール( Slack、Teams)を活用 し、必要に応じてチーム・組織横断チャンネルを作成 意思決定 後追いできる記録 • 〇〇 Decision Record(ADRなど)、デザイン doc、 ポス トモーテムなど記録のルール化
  22. API開発のコラボレーション方法 2023 State of the API Report https://voyager.postman.com/pdf/2023-state-of-the-api-report-postman.pdf #1 コラボレーションツールを活用

    した開発 50% コラボレーションツール例: GitHub/Postman #2 API成果物のコード管理サービ スへの登録・公開 39% コード管理サービス例: GitHub/GitLab/Bitbucket #3 API成果物のURL共有 39% 成果物例: OpenAPI / Postman Collection #4 APIポータルにドキュメントを登 録・公開 @postman_japan 2023年 Postman State of API report
  23. APIプラットフォーム Postmanの API開発ライフサイクルにおける各ステージでの活用例 定義 設計 開発 テスト セキュリティ デプロイ 監視・観測

    ビジネス システム Security ・・・ ドキュメント コード管理 システム設定 モック API Contracts (スキーマ) APIサーバー 開発 API Gateway 開発 トラフィック キャプチャ セキュリティ テスト 要件 Postman コレクション generate パフォーマンス テスト Contracts テスト E2E テスト ソースコード 成果物 commit 自動テスト APIサーバー Build/Deploy API Gateway Build/Deploy CI/CD ・・・ 配布 モニター アラート APM レポート APIカタログ API 開発ポータル trigger integration trigger ユーザー フィードバック Feedback loop UIテスト Stub generate @postman_japan
  24. API開発で取り返しのつかない“大ゴケˮを阻止するためのヒントを4つの観点でお話しま した • APIデザイン ◦ 利用者ニーズをまず考え、使いやすさを検証し、非機能要件は設計段階で • APIテスト ◦ セキュリティテスト(中でも認証・認可)は重点的に行い、点ではなく線で継続的に守る

    • ドキュメント ◦ ドキュメント書きましょう。実装とのズレを無くすべく、ドキュメント/仕様の生成はできるだけ自動 化し、実装との整合性を自動検証する • コラボレーション ◦ コラボレーションツール・フローを整備し、協働・知見記録・共有する文化を醸成する @postman_japan
  25. Spec Hubによる高品質なAPI仕様の設計・管理 Spec Hubの主要機能 • API 設計 ◦ OpenAPI3.0とAsyncAPI2.0 ◦

    スキーマ定義(インポート可能) ◦ API定義の自動バリデーション ◦ ガバナンスポリシーのチェック ◦ コレクション生成(テスト、ドキュメント が可能な形式) ◦ ドキュメントのライブプレビュー • チーム開発支援 ◦ API共同設計 ◦ ロールベースのアクセス制御 SpecHub https://www.postman.com/product/spec-hub/ API設計 ボタンクリックで仕様から コレクション生成
  26. モックサーバーを活用したAPIプロトタイピングと仮説検証 • モックサーバー(PostmanのモックAPIサービス)を活用することで API実装前にAPIの検証をすすめること ができる(APIプロトタイピング開発) • API設計段階でモックAPIを通じた検証を通じて、 API仕様を洗練化させることができる @postman_japan API設計

    要件 / ゴール API定義 コレクション ドキュメント作 成 モック作成 (モックサーバー) テスト作成 インポート 直接コレクションを作成 (プロトタイピング) 外部でAPI定義を作成 API定義 API定義からコレクションを生成
  27. Postmanを活用したAPIテストのカバーエリア • UIテスト • E2Eテスト • リグレッションテスト • シナリオテスト •

    インテグレーションテスト • コントラクトテスト • ユニットテスト • セキュリティテスト • ユーザビリティテスト • パフォーマンステスト 機能要件テスト 非機能要件テスト E2E Integration API Unit コスト 実行時間 不確実要素 テスト数 テストのピラミッド テスト @postman_japan
  28. 実行 実行結果詳細表示 サマリー結果表示 順番入れ替え可能 実行方法選択 手動 / スケジュール実行 イテレーション数 遅延秒数

    データファイル 指定可能 選択 コレクションメニュー コレクションランナー実行方法設定 @postman_japan テスト シナリオテスト・データ駆動テスト コレクションランナーにより複数APIで構成されるテストの手動・定期実行が可能
  29. Postmanモニターで定期的にAPIの健全性をテスト • コレクションごとにモニターを設定 • テスト実行頻度 ◦ 5分毎〜設定可能。ただし無料プランは一時間毎〜 • テスト実行リージョン選択 ◦

    複数リージョンからの APIテスト実行が可能 • スタティックIPを持つモニター指定 ◦ 要Professional / Enterpriseプラン • アラート通知設定 ◦ メール通知、or インテグレーション設定 でslack、 PagerDutyなど他チャンネルへの通知も可能 • リトライ、タイムアウトなど設定可能 リクエスト元リージョンの選択 Setup a monitor in Postman https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/ 監視・観測 @postman_japan テスト
  30. オブザーバービリティサービスとのインテグレーション インテグレーション設定により Postmanモニターで閾値を越えたテスト失敗数が確認されたら外部オブザーバー ビリティサービスにイベントの送信が可能 イベント 送信 PagerDuty Datadog NewRelic Observe

    your API performance using monitor integrations https://learning.postman.com/docs/designing-and-developing-your-api/observing-an-api/observing-an-api/ @postman_japan Datadog dashboardイメージ 監視・観測 テスト
  31. 継続的なAPIセキュリティとガバナンスの検証 代表的なチェック・管理内容。各フェーズやCI/CDなどからの継続的な実施が可能 APIセキュリティ • セキュリティ衛生状態 • 認証と認可の脆弱性 • クォータとスロットリングの実装 •

    適切なセキュリティヘッダー • ロギングとモニタリングの実践 • API文書の適切な管理 • カスタムルール、etc. https://www.postman.com/api-platform/api-security/ APIガバナンス • 全体統制の設定 ◦ APIの文書化、テスト実施、メンテナンス状 況、誤ってトークンを公開していないか、な ど • カスタムルール、etc. https://www.postman.com/api-platform/api-governance/ セキュリティ ガバナンス @postman_japan
  32. Postman Enterprise: 大規模で安全なコラボレーションの実現 コラボレーション機能 ✦ フォーク ✦ バージョン管理 ✦ Pullリクエスト

    ✦ コメント ✦ 共有 ✦ グループ ✦ ワークスペース セキュリティ機能 ✦ SSO ✦ SCIM ✦ きめ細かいRBAC ✦ 公開リンク機能 ✦ ドメインキャプチャ ✦ シークレットスキャナー プライマリーコレクション・ワークスペース プライベート APIネットワーク パブリック APIネットワーク チーム B ワークスペース チーム C ワークスペース チーム Dワークスペース チーム Eワークスペース チームAワークスペース 外部のワークスペース コラボレーション