失敗から学ぶAPIファースト / API first learning from failure

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

View Slide

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

View Slide

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

View Slide

APIファーストとは何か？

View Slide

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

View Slide

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

View Slide

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

View Slide

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ファーストの概念は
十分に理解されているようです

View Slide

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

View Slide

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

View Slide

コードファーストとは？
● 焦点は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とのインテグレーションテストも後付け
テスト作成
ドキュメント作成
デバッグ
実装
コーディング
統合
デプロイ
コードリポジトリ

View Slide

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%)

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

APIファーストとは？
● 焦点はAPIの設計（システムの抽象的な「契約」）
● 実装前にAPI仕様を設計し、モック、ドキュメント、テストも作成する
API-first software development for modern organizations　
API設計
テスト
APIドキュメント
作成
モック作成
実装
コーディング
統合
テスト実行
サーバー環境
Dev
Stage
Prod
モック活用
テスト
ドキュメント
活用
コードリポジトリ
モックを元にレビューや
フィードバックを受け
設計内容を洗練させる
check-in
デプロイ
エンドポイント
にテスト
API開発環境

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

APIはプロダクト
API as a Product

View Slide

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

View Slide

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

View Slide

APIライフサイクル

View Slide

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

View Slide

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

View Slide

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

View Slide

"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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

アーキテクチャドライバー（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
機能適合性性能効率性互換性使用性信頼性セキュリティ保守性移植性

View Slide

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

View Slide

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

View Slide

アーキテクチャはトレードオフ
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)

View Slide

適切なドキュメントを早い段階で用意
ドキュメント＝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

View Slide

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/

View Slide

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

View Slide

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

View Slide

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

View Slide

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/

View Slide

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

View Slide

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

View Slide

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

View Slide

代表的なチェック・管理内容。各フェーズや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/

View Slide

コラボレーション
APIに関わる人々同士の連携

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

ディスカバリ
利用者がAPIを見つけやすく

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

API提供者と利用者を支援する
APIプラットフォーム

View Slide

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

View Slide

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

View Slide

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

View Slide

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

View Slide

まとめ

View Slide

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

View Slide


View Slide

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

View Slide

失敗から学ぶAPIファースト / API first learning from failure

失敗から学ぶAPIファースト / API first learning from failure

Yoichi Kawasaki

More Decks by Yoichi Kawasaki

Other Decks in Technology

Featured

Transcript