All rights reserved by Postman Inc 失敗から学ぶAPIファースト 正しいデザインからはじめるアーキテクチャ選定、 開発ライフサイクル＆コラボレーション Presentation slides for ServerlessDays Tokyo 2023 川崎庸市 Postman株式会社

Technology Evangelist Postman株式会社 川崎 庸市 / Yoichi Kawasaki @postman_japan @yokawasa

本日のゴール ● APIファーストの考え方と実践方法を理解いただく ● 今後のAPI開発に役立てていただく

APIファーストとは何か？

APIファーストと聞いて どういうイメージを持ちますか？

MACHアーキテクチャ？ Microservices-based, API-first, Cloud-native SaaS, Headless 最近よく聞くアーキテクチャの一つ。 マイクロサービス、API ファースト設計、クラウドネイティブ活用、ヘッドレス構成の 4 つ で、迅速な開発、スケーラビリティ、柔軟性、セキュリティなどを実現するらしい What is MACH Architecture? https://www.sunriseintegration.com/learn/what-is-mach-architecture

Beyond the Twelve-Factor App？ 2012年にTwelve Factor Appとして公開されたクラウドネイティブアプリが備えるべき 12の特徴に、米Pivotal社が2016年 にクラウドネイティブアプリ設計と開発の進化を反映して 15の要素に再編したもの Beyond the Twelve-Factor App https://tanzu.vmware.com/content/blog/beyond-the-twelve-factor-app 1. Codebase 2. Dependencies 3. Configuration 4. Backing Services 5. Build, release, run 6. Processes 7. Port binding 8. Concurrency 9. Disposability 10. Dev/prod parity 11. Logs 12. Admin processes 12FA Beyond the 12FA 1. One codebase, one application 2. API first 3. Dependency management 4. Design, build, release, and run 5. Configuration, credentials, and code 6. Logs 7. Disposability 8. Backing services 9. Environment parity 10. Administrative processes 11. Port binding 12. Stateless processes 13. Concurrency 14. Telemetry 15. Authentication and authorization

2022 State of the APIレポートによると 2022 State of the API report https://voyager.postman.com/doc/postman-state-of-the-api-2022.pdf #1 開発前にAPIスキーマ設計 (38%) #2 システム連携より前にAPI開発 (31%) #3 API設計より前にビジネス要件定義(18%) 「API ファースト」とは何を意味しますか? の質問に対する回答 （対象: 37,000以上の開発者 + API専門家） APIファーストの概念は 十分に理解されているようです

今回敢えてAPIファーストの話をする目的は 理解と実践のギャップを埋めるため APIファーストの概念は理解されているかもしれませんが、実際にそれを実践することは 難しいことがあります。理論だけではなく、実際の課題や実践手法を理解いただき、皆さ んのAPIファーストに対する認識を高めていただきたい。

２つのソフトウェア開発哲学 要件 要件 コード APIデザイン + API Spec API Docs / Tests コード Comment Annotation + API Docs API Tests → コードファースト APIファースト (デザインファースト)

コードファーストとは？ ● 焦点は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 に依存するチームは開発を先にすすめられない（並行開発できない） APIドキュメント作成やAPIとのインテグレーションテストも後付け テスト作成 ドキュメント作成 デバッグ 実装 コーディング 統合 デプロイ コードリポジトリ

API利用における障壁No1はドキュメント不足 2023 State of the API Report https://voyager.postman.com/pdf/2023-state-of-the-api-report-postman.pdf #1 ドキュメント不足 (52%) #2 APIの発見が困難 (32%) #3 時間がない(28%) #4 知識不足(26%)

そもそも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を組 み合わせて利用

品質担保のためには質の高いテストが必要 UI Tests E2E API Tests Integration Tests Component Tests Unit Tests コスト 実行時間 不確実要素 テスト数 テストのピラミッド

"Testing shows the presence, not the absence of bugs." Edsger W. Dijkstra at NATO Software Engineering Conference 1969 （意訳）テストによってバグの存在が明らかになる つまり、網羅性のある質の高いテスト戦略が品質保証の鍵となる

API依存チームが並行に開発を進められない問題 独立性を目指しマイクロサービスアーキテクチャを採用し、アーキテクチャに見合うよう 組織構造も最適化したとしてもサービス間でAPI依存がある限り開発スピードや柔軟 性の改善はできない Service A Service B Service C API 未完成 依存 箇所 依存 箇所 API待ち API待ち

フィードバックが開発プロセスの後半になる問題 APIの使われ方が定まり、インテグレーションテストなどの実施が後半になるため問題が あった場合の変更コストが大きい。特に、セキュリティ、性能、データ構造の問題は致命 的になりうる ● APIの使われ方が想定していたものと違い、複数サービスをまたぐ分散トランザクション処理が必要 になった。例）SAGAパターン（実装と管理が複雑）への変更 ● パフォーマンス問題のためデータ構造やデータストアの変更を余儀なくされた。例）一部のデータを RDBMSからNoSQL管理に変更 ● セキュリティ脆弱性が見つかり、抜本的な変更を余儀なくされた Define Design Develop Test Deploy Observe Distribute 後ろのフェーズになればなるほど改修コストが大きい

コードファースト アプローチの問題点まとめ ● ドキュメント不足によるコラボレーションへの弊害 ○ 開発者、テスター、SREなど関係者間のコラボレーションの不足によるプロジェクト進行や品質 への影響 ● 並行開発できない（同期フロー）問題 ○ APIが完成するまで、依存するチームの開発が滞り、製品全体の納品が遅れる ● フィードバックが開発プロセスの後半になる問題 ○ APIの仕様確定やテスト実施が後半になるため問題があった場合の変更コストが大きい。特 に、セキュリティ、性能、データ構造問題は致命的になりうる

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開発環境

API 仕様からドキュメント、モック生成？ OpenAPI ツール群 https://tools.openapis.org/ 例えば次のようなツールを使えば実現できます Postman https://postman.com

モックAPIを介して並行開発ができる API実装との依存関係が分離され、他のチームの作業から独立して作業を進めることが できる。プロジェクト全体の開発時間を最小限に抑えられる。 Service A Service B Service C API 未完成 依存 箇所 依存 箇所 モック API APIドキュメント APIテスト

初期段階でフィードバックループが回せる 最初に、APIのデザイン、ドキュメント、モックなどが揃っているので、初期段階でフィード バックを取得することができる。これにより、変更コストがまだ比較的低いうちに、チーム が方向転換したり、新しい変更に適応したりできる。結果的に、全体的なコスト削減も望 める Define Design Develop Test Deploy Observe Distribute 変更コストが低いうちに変更、方向転換ができる FB FB FB FB

実装とインターフェースの分離による モジュラリティと拡張性の向上 実装とインターフェース（API）が分離されサービスの疎結合化ができるようになり、制約 はデータモデルとビジネス ロジックによってのみ受け、それ以外は、既存のインターフェ イスやフレームワークに束縛されずに進化できるようになる User Interface Business Logic Data Interface Database Module or Service Method or API アプリ構築前に、最初に API を設計して構築する例 API-first software development for modern organizations　 https://medium.com/better-practices/api-first-software-development-for-modern-organizations-fdbfba9a66d3

ここまでの話はどちらかといえば デザインファースト寄りの話。 APIファーストが目指す世界観は これだけではない

APIファーストの世界 https://api-first-world.com/ja/

APIファーストの世界 https://api-first-world.com/ja/

APIはプロダクト API as a Product APIファーストの世界 https://api-first-world.com/ja/

APIをプロダクトとしてライフサイクル全体で管理する APIは後付で構築するものではなく、他のプロダクトやサービスと同じように、戦略的な デジタルプロダクトとしてライフサイクル全体で管理する

Planning Defining Designing Building Testing Deployment SDLC (Software Development Life Cycle)

APIライフサイクル

API提供者と利用者両方のAPIライフサイクルをサポート API 提供側 ライフサイクル API 利用側 ライフサイクル テスト 開発 設計 定義 デプロイ デプロイ 配布 観測 観測 テスト 評価 統合 発見 セキュリ ティ Postman例

APIファーストな開発ワークフロー例 API Spec API Documentation Mocks Tests Code Stubs Client SDK Defining & Designing Building Testing Deployment Monitoring & Observing Existing Code

正しく設計するとは？ 正しいAPIデザインの特徴 ● ユーザーファースト ○ API設計をユーザーの視点から行う ● RESTful原則の遵守 ○ リソース、エンドポイント、 HTTPメソッドなど ● エラーハンドリング ○ エラーハンドリングの仕組み、一貫性のあるエラーコードやメッセージ、適切なス テータスコード ● バージョニング ● セキュリティ ○ 適切な認証・認可メカニズムの導入やデータの暗号化、など ● 性能と拡張性 ○ リクエストとレスポンス最適化、キャッシング戦略、など ● クリアなAPI仕様とそのドキュメント ● Microsoft learn: RESTful Web API の設計 ● 政府CIOポータル: APIテクニカルガイドブック

正しく設計するとは？ 正しいAPIデザインの特徴 ● ユーザーファースト ○ API設計をユーザーの視点から行う ● RESTful原則の遵守 ○ リソース、エンドポイント、 HTTPメソッドなど ● エラーハンドリング ○ エラーハンドリングの仕組み、一貫性のあるエラーコードやメッセージ、適切なス テータスコード ● バージョニング ● セキュリティ ○ 適切な認証・認可メカニズムの導入やデータの暗号化、など ● 性能と拡張性 ○ リクエストとレスポンス最適化、キャッシング戦略、など ● クリアなAPI仕様とそのドキュメント ● Microsoft learn: RESTful Web API の設計 ● 政府CIOポータル: APIテクニカルガイドブック

"In the API space, we build something on a machine for a machine to use and this is wrong because there are people on the other side of API clients." Ronnie Mitra, Director of Technology at Publicis Sapient API クライアントの向こう側には人がいる https://medium.com/better-practices/design-apis-like-you-design-user-experience-a7adeb2ee90f

デザイン、モック作、フィードバックループ API Spec API Documentation Mocks Tests Code Stubs Client SDK Defining & Designing Building Testing Deployment Monitoring & Observing Existing Code

API設計支援ツール (APIビルダー) OpenAPI Postman Collection RAML WSDL GraphQL ProtoBuf チームによるAPI設計を支援するツールです。直感的なUIを介してAPIの構造を定義できます APIビルダーの主要機能 ● API設計 ○ スキーマ定義（インポートも可能） ○ API定義のバリデーション ○ 定義からサーバーコード生成 ○ テスト、ドキュメント生成 ○ コレクション生成 ● チーム開発支援 ○ チーム間のAPI共有 ○ コメント、Changelog ● APIバージョン管理 ○ コードリポジトリ(GitHub, GitLab, Bitbucket, and Azure)と同期 Postman例

正しいデザインゴールから始めるアーキテクチャ選定 APIファースト x アーキテクチャ設計原則 APIデザイン ゴール アーキテクチャ ドライバー アーキテクチャ 設計原則

アーキテクチャドライバー（Architecture Drivers） アーキテクチャドライバーとは ● アーキテクチャの決定要因となるソフトウェアへの要求 ● 最終的なアーキテクチャへの道筋を作るために必要なガイドラインのようなもの ● 内容はプロジェクトの要件 / コンテキストによって異なる（全てに当てはまる黄金律はない） Architectural Drivers in Modern Software Architecture | by Erik Franzen | Medium アーキテクチャドライバーの4つのグループ ● 技術制約 (Technical Constraints) ○ プログラミング言語、OS / ライブラリ、実行環境 ● ビジネス制約 (Business Constraints) ○ タイミング、予算、チーム構成. ● 機能要求 (Functional Requirements) ○ ユーザーストーリー、ユースケース ● 品質特性 (Quality Attributes) ← 特に重要 ○ 信頼性、セキュリティ、変更容易性、使いやすさ、性能

アーキテクチャドライバー（Architecture Drivers） 中でも品質特性は特にアーキテクチャの良し悪しに最も影響を与える要因 機能要求 vs. 非機能要求 ISO/IEC 25010: ソフトウェアの品質特性を表す8つの品質モデル ISO/IEC 25010 (iso25000.com) https://iso25000.com/index.php/en/iso-25000-standards/iso-25010/45-iso-iec-25010 機能適合性 性能効率性 互換性 使用性 信頼性 セキュリティ 保守性 移植性

（クラウドネイティブ）アーキテクチャ設計原則 色々あります。思いつくものいくつか並べてます。人類の叡智を活用しよう。 ● クリーンアーキテクチャ ● DDD（サービスの適切な分離） ● 疎結合・高凝集・責務配分 ● 人間はボトルネック（自動化、コード化） ● Design for Failure、回復力を高める ● 変更容易性を高める ● 直列/並列、同期/非同期、を使い分ける ● 適材適所のデータベース ● コスト競争力を高める ● YANGI ● 標準化されているものを選ぶ（巨人の肩の上に立つ）

アーキテクチャはトレードオフ "There are no right or wrong answers in architecture - only trade-offs." By Neal Ford at Fundamentals of Software Architecture （意訳）アーキテクチャに正解はない - あるのはトレードオフのみ

アーキテクチャはトレードオフ EP23: How to choose the right database? Also... (bytebytego.com) APIどうする？：REST vs. GraphQL どこで、何を、どうCacheする? A Crash Course in Caching - Part 1 - by Alex Xu (bytebytego.com)

適切なドキュメントを早い段階で用意 ドキュメント＝API仕様書（説明、サンプル、etc.） ● API仕様ファイル (OpenAPI Specなど) / コードから自動生成す るパターンが多い ● API利用者のTTFC（＊）やAPIの採用率に影響 ● API開発関係者のコラボレーションに影響 OpenAPI Postman Collection RAML WSDL GraphQL Schema generate TTFC: Time to first call。詳細は後述のページ参照 Defining & Designing ● APIエンドポイント ● 認証 / セキュリティ ● リクエスト/ レスポンス ● エラーハンドリング ● 使用例 ● 制限事項 ● 問い合わせ先 ● etc

Time to First Call (TTFC) どれだけ短時間でAPIの初回呼び出しができるかを表すメトリクス。API提供者はTTFC を分析しAPIを改善し、その短縮を目指す ● Web分析やユーザーフィードバックにより測定 ○ Web分析計測：発見時点 (Web サイトへの訪問、サインアップなど) から最初のAPI 呼び出しまでの時間差 ● メトリクス分析からの洞察 ○ 開発者が閲覧からサインアップまでに費やす時間が長い場合 → Webサイトやドキュメントの品質に起因する可能性 が考えられる ○ サインアップから最初の API 呼び出しまでの時間が長い場合 → ガイドページの有効性や製品の使いやすさに起因 する可能性が考えられる The Most Important API Metric Is Time to First Call https://blog.postman.com/the-most-important-api-metric-is-time-to-first-call/

"Testing shows the presence, not the absence of bugs." Edsger W. Dijkstra at NATO Software Engineering Conference 1969 （意訳）テストによってバグの存在が明らかになる つまり、網羅性のある質の高いテスト戦略が品質保証の鍵となる 書こう、テスト！ 再掲

テスト自動化 継続的なテストを通じて品質を担保 ● 早い段階でテスト（シフトレフト） ● リリース後もテスト ● 継続的にテスト ソフトウェアテストの歴史と近年の動 https://www.slideshare.net/Bugler/ss-139696080

Postmanスクリプトでテストや自動化を記述 ● Postman サンドボックスで実行 ● Built-inのJavaScript APIをpm、postmanオブジェクトを通じて利用可能 ● Mochaベースのテストフレームワークを利用、AssertionライブラリとしてChaiが利用可能 ● 豊富なスニペットとサンプルスクリプト集が用意されている ● 新機能: Postbot（AIを活用したスクリプト生成アシスタント) スクリプト Postbot スニペット ローコード 支援機能 Postman例

TDD & BDD in Postman ● モックはモックサーバーを活用する ● 継続的なテスト実行オプション ○ コレクションランナーの定期スケジュール実行 ○ モニター定期スケジュール実行 ○ CLIを活用したCI/CD実行 Postman例 https://medium.com/@fatoniahmad.mail/test-driven-development-tdd-restf ul-api-using-mock-server-postman-1fd1cb271ed0 https://blog.postman.com/writing-a-behaviour-driven-api-testing-e nvironment-within-postman/

Postbot - 生成AIがテスト作成を支援 生成されたテストを確認 Postman例

CI/CDで継続的なテスト実行 Postman例 GitHub ActionsでのPostmanテストの実行イメージ

APIセキュリティとガバナンス ライフサイクルで一貫したセキュリティやガバナンスの確認実施する できるだけ早い段階から (シフトレフト) ＋ 継続的に実施することが重要 APIセキュリティ API が組織が設定したセキュリティルールに従ってい るか確認・管理する。APIスキーマやレスポンスなどを チェックして開発者にセキュリティガイドラインを提供。 後回しにできない作業。 APIガバナンス API が組織が設定した標準ルールに従って設計、構 築、テスト、配布されることを管理・保証すること。全て のAPIにわたり品質、一貫性、セキュリティ、コンプライ アンスを目指す。 Define Design Develop Test Deploy Observe Distribute check check check check check 後ろのフェーズになればなるほど改修コストが大きい What's changed in the Top 10 for 2021 in OWASP TOP10 https://owasp.org/Top10/

APIセキュリティとガバナンス 代表的なチェック・管理内容。各フェーズやCI/CDなどからの継続的な実施が可能 Postman例 APIセキュリティ ● セキュリティ衛生状態 ● 認証と認可の脆弱性 ● 読み取りと書き込みの粒度 ● クォータとスロットリングの実装 ● 適切なセキュリティヘッダー ● ロギングとモニタリングの実践 ● API文書の適切な管理 ● カスタムルール、etc. https://www.postman.com/api-platform/api-security/ APIガバナンス ● APIの文書化、テスト実施、メンテナンス状況、 誤ってトークンを公開していないか、など APIご と、組織ごとに、個別もしくは全体統制の設定 ● カスタムルール、etc. https://www.postman.com/api-platform/api-governance/

コラボレーション APIに関わる人々同士の連携 APIファーストの世界 https://api-first-world.com/ja/

API開発におけるコラボレーションの障壁 サイロ化されたチーム・開発者 ビジネスユニットや地域を越えた API 共同作業 多様なステークホルダー、 不適切なAPI共有方法 パートナー、パブリック、内部関係者間の API利用 異なるプロセスやツール群 単一の信頼できる情報源を持たない広範な API ポートフォリオ

コラボレーションの改善、何ができる？ API開発に関わるチームのコラボレーション改善のためにできること ● 詳細ドキュメント（設計、API仕様、など）の準備 ● ドキュメントやソースコードを関係者いつでもすぐに触れられるようにしておく ● クロスファンクチームの設立 ● 共通目標の確立 ● プロジェクト管理やコラボレーションツール（Slack, etc.）の活用 ● 仕様やコードのレビュー

コードの共同所有 ( collective code ownership ) Martin Fowler - CodeOwnership https://martinfowler.com/bliki/CodeOwnership.html https://chat.openai.com/

コラボレーション例 - APIライフサイクルにおける共同開発 Postman例

(外部の) API利用者とのコラボレーションも考慮 API提供者と利用者間のコラボレーション改善にできること ● API仕様書、ドキュメントの公開 ● フィードバック収集、コミュニティサポートの仕組み提供 ○ GitHub、フォーラム、slackチャンネル、メーリングリスト、etc ● トレーニングや教育コンテンツ ● リリースノート ● サンプルコード

ディスカバリ 利用者がAPIを見つけやすく APIファーストの世界 https://api-first-world.com/ja/

利用者がAPIを見つけやすくする、何ができる？ ● API仕様書、ドキュメントの公開 ● デベロッパーポータルの構築・公開 ● APIディスカバリプラットフォームの活用 ○ APIマーケットプレイス

Postman APIネットワーク Postman API ネットワークは、 API 利用者と API 提供者の双方が API を簡単に発見、探索、共有でき るユニークな場所を提供します。 Postman API ネットワークには2つの種類があります： パブリック APIネットワーク プライベート APIネットワーク APIネットワーク Postman例

パブリックAPIネットワーク パブリックAPIネットワークは、あらゆる利用者に公開されているAPIが含まれる世界最大規模のパブリッ クAPI成果物のカタログです。パブリックワークスペースを通じて組織のパブリック API を簡単に共有し たり、Salesforce、Paypal、Notion のような企業の何千ものパブリック API を発見したりすることがで きます。 ● 広範な利用者・開発者へのアクセス ● 利用者のTime to first callの短縮化 ○ 利用者は公開されているコレクションを Forkして利用 ○ 利用者のAPIテストが容易になる ● 利用者からのフィードバックと改善 Postman例

プライベートAPIネットワーク プライベート API ネットワークは組織内のすべての内部APIをまとめている一元化された場所（内部APIカ タログ）であり、組織内の内部API成果物を簡単に発見、探索、共有ができます。 これにより誰もが組織のAPIの全体像を把握できるようになるため、開発者と業務責任者の双方にとって メリットがあります。 ● 組織内の機能重複の排除 ● API知見・ノウハウの共有 ● 組織内のAPI利用動向把握 ● 利用者からのフィードバックと改善 Postman例

API提供者と利用者を支援する APIプラットフォーム APIファーストの世界 https://api-first-world.com/ja/

Postmanも選択肢の１つ https://www.postman.com/state-of-api/api-global-growth/

豊富なツール利用オプション Postman Desktop App Postman Web Postman VS Code Extension Postman CLI Postman例

さまざまなAPIプロトコルをサポート Postman例

APIライフサイクル全体で支援 監視 モックサーバー APIテスト ドキュメント作成 コレクション APIネットワーク (private/public/partner) ソースコード バージョン管理システム API設計 SPECの生成 POSTMANにSPEC をインポート 双方向の同期 APIビルダー SPECの設計 標準ルールの適用 静的解析ルールの適用 ポリシー制御とその自動化 POSTMANアセット の自動生成 CI/CD 自動APIテスト APIの のデプロイ APIデプロイ先環境 Postman CLI 監視観測 連携 開発者体験向上 プロダクトリリースのリードタイム短縮化 ワークスペース を通じた共有とコラボレーション 社内だけでなくパートナー、社外 との共同作業 APIの採用を促進 開発者体験向上 APIセキュリティ とガバナンス 自動化、再現性の強化 POSTMANアセット へのアクセスと生成 利用者 VS Code ブラウザ アプリ トリガー Postman例

まとめ

API開発における１つのアプローチであるAPIファーストの考え方、原則、実践方法に ついてご紹介しました。 APIファーストの考え方や実践方法についてご理解いただけましたでしょうか？ みなさまの今後のAPI開発の参考になりましたら幸いです。

APIファーストの世界 https://api-first-world.com/ja/

ご清聴いただき、ありがとうございました