APIをもっと使ってもらうには？- APIファースト戦略のすすめ / Recommendation of API-first strategy

Presentation Slides for Postman Tokyo Meetup 2023.11
Session title: APIをもっと使ってもらうには？ - APIファースト戦略のすすめ
Date: 2023/11/08

Transcript

1. All rights reserved by Postman Inc APIをもっと使ってもらうには？ APIファースト戦略のすすめ 川崎庸市 Postman株式会社 Presentation slides for Postman Tokyo Meetup 2023.11
2. Technology Evangelist Postman株式会社 川崎 庸市 / Yoichi Kawasaki @yokawasa @postman_japan
3. APIをもっと使ってもらうには？
4. APIにまつわるさまざまな課題 • 利用者ニーズ、シナリオにマッチしない • 再利用性 / 汎用性がない • 十分な認証・認可、セキュリティ対策がされていない • 一貫性がない • 適切なエラーハンドリングがされていない • パフォーマンスや拡張性がない • バージョン管理が不十分、互換性が維持されない • 標準化仕様がサポートされていない • APIドキュメントがない、見つからない • APIドキュメントが古い • APIが見つからない
5. 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利用における障壁
6. レポート結果から分かる APIをもっと使ってもらうためにすべきこと 良質なAPIドキュメントを用意する APIを見つけやすくする 再利用性 / 汎用性のあるAPIを用意する
7. レポート結果から分かる APIをもっと使ってもらうためにすべきこと 良質なAPIドキュメントを用意する APIを見つけやすくする 再利用性 / 汎用性のあるAPIを用意する API設計 API設計 API構築 API ディスカバリ
8. レポート結果から分かる APIをもっと使ってもらうためにすべきこと 良質なAPIドキュメントを用意する APIを見つけやすくする 再利用性 / 汎用性のあるAPIを用意する API設計 API設計 API構築 API ディスカバリ API提供者として効率的、安定的、継続的に これらを提供していくことが重要
9. APIを中心としたサービス戦略 APIファースト戦略
10. APIファーストの世界 https://api-first-world.com/ja/
11. APIファースト戦略とは？ • APIに対する位置づけ、考え方 ◦ APIはプロダクト（主要ソフトウェア構成要素、主要ビジネスアセット） ◦ APIがビジネスにもたらす価値に焦点を当てる ◦ API中心：内外サービスをAPIを通じて活用しビルディングブロックで構築 • API開発モデル ◦ APIを最優先に開発（APIを後回しにしない） ◦ コードを書く前にAPIを設計・構築 • APIファースト採用のために必要な取り組み ◦ APIライフサイクルを理解しライフサイクル全体で取り組む ◦ APIの継続的な保守・運用のためのチーム体制を構築する API-First Guide https://www.postman.com/api-first/
12. APIはプロダクト = 第一級市民 • APIは後付で構築するものではなく、最優先で構築するもの • 戦略的なビジネスアセットとしてライフサイクル全体で管理する • 一回きりのプロジェクトではなく、継続的に管理する • 継続的な保守・運用のためのチーム体制を構築する
13. Planning Defining Designing Building Testing Deployment SDLC (Software Development Life Cycle)
14. API提供者と利用者のAPI開発ライフサイクル
15. コードを書く前にAPIを設計・構築するとは？ 要件 API設計 コード API Spec作成 APIドキュメント作成 モック作成 テストコード作成 API定義・生成 テスト モック、テスト結果を元にレビューや フィードバックを受け設計内容を洗練させ る作業を繰り返す
16. モックサーバー - モック用サービス 実際のサーバーと同じような振る舞いをする架空のサーバ。 Postmanではモックサーバーはクラウドに作成さ れ専用URLが発行される（デフォルトパブリックでプライベート設定可能） 。API 実装との依存関係が分離され、 他のチームの作業から独立して作業を進めることができる Service A Service B Service C API 未完成 依存 箇所 依存 箇所 モック サーバー @postman_japan モックテスト
17. API設計の指針 • ユーザーファースト ◦ API設計をユーザーの視点から行う • RESTful原則の遵守 ◦ リソース、エンドポイント、HTTPメソッドなど • エラーハンドリング ◦ エラーハンドリングの仕組み、一貫性のあるエラーコードやメッ セージ、適切なステータスコード • バージョニング ◦ しっかりバージョン管理、互換性を維持 • セキュリティ ◦ 適切な認証・認可メカニズムの導入やデータの暗号化、など • 性能と拡張性 ◦ リクエストとレスポンス最適化、キャッシング戦略、など • 明確なAPI仕様と詳細ドキュメント • Microsoft learn: RESTful Web API の設計 • 政府CIOポータル: APIテクニカルガイドブック
18. API 仕様からドキュメント、モックの生成 OpenAPI ツール群 https://tools.openapis.org/ 例えば次のようなツールを使えば実現できます Postman https://postman.com
19. ２つのAPI開発モデルを比較 要件 要件 コード API設計 API Docs / Tests コード Comment Annotation API Spec API Docs API Mock API Tests コードファースト APIファースト
20. コードファースト開発モデル 要件 コード API Docs / Tests ポイント • 要件を元にAPI実装後にAPIテスト・ドキュメント作成。 • 焦点はAPI (インターフェース) ではなくコア機能。APIは後付 け。APIを実装する段階になるとコア機能はほぼ完了 メリット - 迅速なプロトタイピング - 柔軟性と適応力。要件の変更や市場の変化に迅速に対応 デメリット - API内容がコア機能や利用テクノロジーに引っ張られやすい - APIドキュメントや結合テストが後付けになるため、品質リスクや途中開発 における関係者間のコラボレーションへの弊害 - 仕様確定やテスト実施によるフィードバックが開発プロセス後半になるた め、問題がある場合の変更コストが大きい
21. APIファースト開発モデル ポイント • APIコードを書く前にAPIを設計・構築 • API設計フェーズでフィードバックループを通じて設計内容を洗 練化 メリット • 設計品質、開発者エクスペリエンス向上 • 要件・設計などの問題について早期発見ができ、変更コストが低いうちに変 更、方向転換ができる。不確実性に対して柔軟。 • 設計段階で、APIドキュメントやテスト生成され、比較的初期段階でも関係 者間でコラボレーションが可能 デメリット • 設計フェーズに時間がかかる • 要件の変更に対する対応に時間がかかりがち（設計から入るため） 要件 コード API設計
22. 利用者がAPIを見つけやすくするための活動
23. 利用者がAPIを見つけやすくするための活動 • API仕様書、ドキュメントの公開 • デベロッパーポータルの構築・公開 • APIディスカバリプラットフォームの活用 ◦ APIマーケットプレイス
24. APIファースト戦略 Recap • APIに対する位置づけ、考え方 ◦ APIはプロダクト（主要ソフトウェア構成要素、主要ビジネスアセット） ◦ APIがビジネスにもたらす価値に焦点を当てる ◦ API中心：内外サービスをAPIを通じて活用しビルディングブロックで構築 • API開発モデル ◦ APIを最優先に開発（APIを後回しにしない） ◦ コードを書く前にAPIを設計・構築 • APIファースト採用のために必要な取り組み ◦ APIライフサイクルを理解しライフサイクル全体で取り組む ◦ APIの継続的な保守・運用のためのチーム体制を構築する API-First Guide https://www.postman.com/api-first/ 再掲
25. APIファースト戦略 Recap 良質なAPIドキュメントを用意する APIを見つけやすくする 再利用性 / 汎用性のあるAPIを用意する API設計 API設計 API構築 API ディスカバリ 効率的、安定的、継続的なAPIサービスの提供 API ライフサイクル全 体
26. PostmanはAPIファースト開発 の実践をサポートする APIプラットフォーム
27. Postmanが支援するAPI提供者と利用者両方の API開発ライフサイクル 提供者・利用者間 コラボレーション API提供者 コラボレーション API利用者 コラボレーション
28. API設計支援ツール - APIビルダー OpenAPI Postman Collection RAML WSDL GraphQL ProtoBuf チームによるAPI設計を支援するツールです。直感的なUIを介してAPIの構造を定義できます APIビルダーの主要機能 • API設計 ◦ スキーマ定義（インポートも可能） ◦ API定義のバリデーション ◦ 定義からサーバーコード生成 ◦ テスト、ドキュメント生成 ◦ コレクション生成 • チーム開発支援 ◦ チーム間のAPI共有 ◦ コメント、Changelog • APIバージョン管理 ◦ コードリポジトリ(GitHub, GitLab, Bitbucket, and Azure)と同期 API設計
29. Postmanスクリプトでテストや自動化を記述 • Postman サンドボックスで実行 • Built-inのJavaScript APIをpm、postmanオブジェクトを通じて利用可能 • Mochaベースのテストフレームワークを利用、AssertionライブラリとしてChaiが利用可能 • 豊富なスニペットとサンプルスクリプト集が用意されている • 新機能: Postbot（AIを活用したスクリプト生成アシスタント) スクリプト Postbot スニペット ローコード 支援機能 テスト
30. 生成AIを活用したテストコード生成 - Postbot https://blog.postman.com/meet-postbot-postmans-new-ai-assistant/ テスト
31. モックサーバー - モック用サービス 実際のサーバーと同じような振る舞いをする架空のサーバ。 Postmanではモックサーバーはクラウドに作成さ れ専用URLが発行される（デフォルトパブリックでプライベート設定可能） 。API 実装との依存関係が分離され、 他のチームの作業から独立して作業を進めることができる Service A Service B Service C API 未完成 依存 箇所 依存 箇所 モック サーバー @postman_japan モックテスト
32. コレクションランナーで複数リクエストのテスト実行 実行 実行結果詳細表示 サマリー結果表示 順番入れ替え可能 実行方法選択 手動 / スケジュール実行 イテレーション数 遅延秒数 データファイル 指定可能 選択 コレクションメニュー コレクションランナー実行方法設定 テスト
33. モニターで複数エリアから定期的にAPIテスト実行 • コレクションごとにモニターを設定 • テスト実行頻度 ◦ 5分毎〜設定可能。ただし無料プランは一時間毎〜 • テスト実行リージョン選択 ◦ 複数リージョンからの APIテスト実行が可能 • スタティックIPを持つモニター指定 ◦ 要Professional / Enterpriseプラン • アラート通知設定 ◦ メール通知、or インテグレーション設定 でslack、 PagerDutyなど他チャンネルへの通知も可能 • リトライ、タイムアウトなど設定可能 リクエスト元リージョンの選択 https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/ 監視・観測
34. Postmanパフォーマンステスト コレクションもしくはフォルダーに登録されているAPIリクエスト群に対して、手軽にAPIクライアントから負 荷をかけ、APIの性能フィードバックをリアルタイムで得られる機能 実行 コレクションランナー実行タイプ設定 テスト (非機能要件)
35. CLIを活用したCI/CD、継続的なテスト実行 GitHub ActionsでのPostmanテストの実行イメージ Postman CLI からのコレクションテスト実行 テスト
36. APIセキュリティとガバナンスの管理 代表的なチェック・管理内容。各フェーズやCI/CDなどからの継続的な実施が可能 APIセキュリティ • セキュリティ衛生状態 • 認証と認可の脆弱性 • 読み取りと書き込みの粒度 • クォータとスロットリングの実装 • 適切なセキュリティヘッダー • ロギングとモニタリングの実践 • API文書の適切な管理 • カスタムルール、etc. https://www.postman.com/api-platform/api-security/ APIガバナンス • APIの文書化、テスト実施、メンテナンス状況、 誤ってトークンを公開していないか、など APIご と、組織ごとに、個別もしくは全体統制の設定 • カスタムルール、etc. https://www.postman.com/api-platform/api-governance/ テスト (非機能要件)
37. コラボレーション - APIの共同開発 コラボレーション 異なるアクセスレベルを設定可能なワークスペースと、その配下のコレクション、API定義、環境、モック、モ ニターなどを通じて、組織や世界をまたいだシームレスなコラボレーションを支援 5つのアクセス共有レベル • パーソナル • プライベート • チーム • パートナー • パブリック
38. コラボレーション - APIの共同開発 コラボレーション
39. Postman APIネットワーク - APIの発見・探索・共有 Postman API ネットワークは、 API 利用者と API 提供者の双方が API を簡単に発見、探索、共有でき るユニークな場所を提供します。 Postman API ネットワークには2つの種類があります： パブリック APIネットワーク プライベート APIネットワーク APIネットワーク ディスカバリ
40. パブリックAPIネットワーク パブリックAPIネットワークは、あらゆる利用者に公開されているAPIが含まれる世界最大規模のパブリッ クAPI成果物のカタログです。パブリックワークスペースを通じて組織のパブリック API を簡単に共有し たり、Salesforce、Paypal、Notion のような企業の何千ものパブリック API を発見したりすることがで きます。 • 広範な利用者・開発者へのアクセス • 利用者のTime to first callの短縮化 ◦ 利用者は公開されているコレクションを Forkして利用 ◦ 利用者のAPIテストが容易になる • 利用者からのフィードバックと改善 ディスカバリ 2023年9月〜 日本語検索サポート
41. プライベートAPIネットワーク プライベート API ネットワークは組織内のすべての内部APIをまとめている一元化された場所（内部APIカ タログ）であり、組織内の内部API成果物を簡単に発見、探索、共有ができます。 これにより誰もが組織のAPIの全体像を把握できるようになるため、開発者と業務責任者の双方にとって メリットがあります。 • 組織内の機能重複の排除 • API知見・ノウハウの共有 • 組織内のAPI利用動向把握 • 利用者からのフィードバックと改善 ディスカバリ
42. 本セッションではAPIをもっと使ってもらうための選択肢の 1つとしてAPIファースト戦略を紹介させていただきました。 今後のAPI開発の参考になりましたら幸いです。 ご清聴いただき、ありがとうございました。