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

Slide 1

Slide 1 text

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

APIをもっと使ってもらうには？

Slide 4

Slide 4 text

APIにまつわるさまざまな課題 ● 利用者ニーズ、シナリオにマッチしない ● 再利用性 / 汎用性がない ● 十分な認証・認可、セキュリティ対策がされていない ● 一貫性がない ● 適切なエラーハンドリングがされていない ● パフォーマンスや拡張性がない ● バージョン管理が不十分、互換性が維持されない ● 標準化仕様がサポートされていない ● APIドキュメントがない、見つからない ● APIドキュメントが古い ● APIが見つからない

Slide 5

Slide 5 text

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利用における障壁

Slide 6

Slide 6 text

レポート結果から分かる APIをもっと使ってもらうためにすべきこと良質なAPIドキュメントを用意する APIを見つけやすくする再利用性 / 汎用性のあるAPIを用意する

Slide 7

Slide 7 text

レポート結果から分かる APIをもっと使ってもらうためにすべきこと良質なAPIドキュメントを用意する APIを見つけやすくする再利用性 / 汎用性のあるAPIを用意する API設計 API設計 API構築 API ディスカバリ

Slide 8

Slide 8 text

レポート結果から分かる APIをもっと使ってもらうためにすべきこと良質なAPIドキュメントを用意する APIを見つけやすくする再利用性 / 汎用性のあるAPIを用意する API設計 API設計 API構築 API ディスカバリ API提供者として効率的、安定的、継続的にこれらを提供していくことが重要

Slide 9

Slide 9 text

APIを中心としたサービス戦略 APIファースト戦略

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

APIファースト戦略とは？ ● APIに対する位置づけ、考え方 ○ APIはプロダクト（主要ソフトウェア構成要素、主要ビジネスアセット） ○ APIがビジネスにもたらす価値に焦点を当てる ○ API中心：内外サービスをAPIを通じて活用しビルディングブロックで構築 ● API開発モデル ○ APIを最優先に開発（APIを後回しにしない） ○ コードを書く前にAPIを設計・構築 ● APIファースト採用のために必要な取り組み ○ APIライフサイクルを理解しライフサイクル全体で取り組む ○ APIの継続的な保守・運用のためのチーム体制を構築する API-First Guide https://www.postman.com/api-first/

Slide 12

Slide 12 text

APIはプロダクト = 第一級市民 ● APIは後付で構築するものではなく、最優先で構築するもの ● 戦略的なビジネスアセットとしてライフサイクル全体で管理する ● 一回きりのプロジェクトではなく、継続的に管理する ● 継続的な保守・運用のためのチーム体制を構築する

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

API提供者と利用者のAPI開発ライフサイクル

Slide 15

Slide 15 text

コードを書く前にAPIを設計・構築するとは？要件 API設計コード API Spec作成 APIドキュメント作成モック作成テストコード作成 API定義・生成テストモック、テスト結果を元にレビューやフィードバックを受け設計内容を洗練させる作業を繰り返す

Slide 16

Slide 16 text

モックサーバー - モック用サービス実際のサーバーと同じような振る舞いをする架空のサーバ。 Postmanではモックサーバーはクラウドに作成され専用URLが発行される（デフォルトパブリックでプライベート設定可能）。API 実装との依存関係が分離され、他のチームの作業から独立して作業を進めることができる Service A Service B Service C API 未完成依存箇所依存箇所モックサーバー @postman_japan モックテスト

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

２つのAPI開発モデルを比較要件要件コード API設計 API Docs / Tests コード Comment Annotation API Spec API Docs API Mock API Tests コードファースト APIファースト

Slide 20

Slide 20 text

コードファースト開発モデル要件コード API Docs / Tests ポイント ● 要件を元にAPI実装後にAPIテスト・ドキュメント作成。 ● 焦点はAPI (インターフェース) ではなくコア機能。APIは後付け。APIを実装する段階になるとコア機能はほぼ完了メリット - 迅速なプロトタイピング - 柔軟性と適応力。要件の変更や市場の変化に迅速に対応デメリット - API内容がコア機能や利用テクノロジーに引っ張られやすい - APIドキュメントや結合テストが後付けになるため、品質リスクや途中開発における関係者間のコラボレーションへの弊害 - 仕様確定やテスト実施によるフィードバックが開発プロセス後半になるため、問題がある場合の変更コストが大きい

Slide 21

Slide 21 text

APIファースト開発モデルポイント ● APIコードを書く前にAPIを設計・構築 ● API設計フェーズでフィードバックループを通じて設計内容を洗練化メリット ● 設計品質、開発者エクスペリエンス向上 ● 要件・設計などの問題について早期発見ができ、変更コストが低いうちに変更、方向転換ができる。不確実性に対して柔軟。 ● 設計段階で、APIドキュメントやテスト生成され、比較的初期段階でも関係者間でコラボレーションが可能デメリット ● 設計フェーズに時間がかかる ● 要件の変更に対する対応に時間がかかりがち（設計から入るため）要件コード API設計

Slide 22

Slide 22 text

利用者がAPIを見つけやすくするための活動

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

APIファースト戦略 Recap ● APIに対する位置づけ、考え方 ○ APIはプロダクト（主要ソフトウェア構成要素、主要ビジネスアセット） ○ APIがビジネスにもたらす価値に焦点を当てる ○ API中心：内外サービスをAPIを通じて活用しビルディングブロックで構築 ● API開発モデル ○ APIを最優先に開発（APIを後回しにしない） ○ コードを書く前にAPIを設計・構築 ● APIファースト採用のために必要な取り組み ○ APIライフサイクルを理解しライフサイクル全体で取り組む ○ APIの継続的な保守・運用のためのチーム体制を構築する API-First Guide https://www.postman.com/api-first/ 再掲

Slide 25

Slide 25 text

APIファースト戦略 Recap 良質なAPIドキュメントを用意する APIを見つけやすくする再利用性 / 汎用性のあるAPIを用意する API設計 API設計 API構築 API ディスカバリ効率的、安定的、継続的なAPIサービスの提供 API ライフサイクル全体

Slide 26

Slide 26 text

PostmanはAPIファースト開発の実践をサポートする APIプラットフォーム

Slide 27

Slide 27 text

Postmanが支援するAPI提供者と利用者両方の API開発ライフサイクル提供者・利用者間コラボレーション API提供者コラボレーション API利用者コラボレーション

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

生成AIを活用したテストコード生成 - Postbot https://blog.postman.com/meet-postbot-postmans-new-ai-assistant/ テスト

Slide 31

Slide 31 text

Slide 32

Slide 32 text

コレクションランナーで複数リクエストのテスト実行実行実行結果詳細表示サマリー結果表示順番入れ替え可能実行方法選択手動 / スケジュール実行イテレーション数遅延秒数データファイル指定可能選択コレクションメニューコレクションランナー実行方法設定テスト

Slide 33

Slide 33 text

モニターで複数エリアから定期的にAPIテスト実行 ● コレクションごとにモニターを設定 ● テスト実行頻度 ○ 5分毎〜設定可能。ただし無料プランは一時間毎〜 ● テスト実行リージョン選択 ○ 複数リージョンからの APIテスト実行が可能 ● スタティックIPを持つモニター指定 ○ 要Professional / Enterpriseプラン ● アラート通知設定 ○ メール通知、or インテグレーション設定でslack、 PagerDutyなど他チャンネルへの通知も可能 ● リトライ、タイムアウトなど設定可能リクエスト元リージョンの選択 https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/ 監視・観測

Slide 34

Slide 34 text

Postmanパフォーマンステストコレクションもしくはフォルダーに登録されているAPIリクエスト群に対して、手軽にAPIクライアントから負荷をかけ、APIの性能フィードバックをリアルタイムで得られる機能実行コレクションランナー実行タイプ設定テスト (非機能要件)

Slide 35

Slide 35 text

CLIを活用したCI/CD、継続的なテスト実行 GitHub ActionsでのPostmanテストの実行イメージ Postman CLI からのコレクションテスト実行テスト

Slide 36

Slide 36 text

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/ テスト (非機能要件)

Slide 37

Slide 37 text

コラボレーション - APIの共同開発コラボレーション異なるアクセスレベルを設定可能なワークスペースと、その配下のコレクション、API定義、環境、モック、モニターなどを通じて、組織や世界をまたいだシームレスなコラボレーションを支援 5つのアクセス共有レベル ● パーソナル ● プライベート ● チーム ● パートナー ● パブリック

Slide 38

Slide 38 text

コラボレーション - APIの共同開発コラボレーション

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

本セッションではAPIをもっと使ってもらうための選択肢の 1つとしてAPIファースト戦略を紹介させていただきました。今後のAPI開発の参考になりましたら幸いです。ご清聴いただき、ありがとうございました。