Postman APIネットワークを使ってAPIを公開しよう

Postmanが備えるAPIカタログ「PostmanパブリックAPIネットワーク」には世界中の企業がAPIを登録し、開発者はそれを利用して素早く開発に取り組んでいます。日本語にも対応した今、誰もが無料で自分のAPIを登録して幅広いユーザーに知ってもらう最適な場です。本トークでは、パブリックAPIネットワークへのAPIの登録のしかたやコツをわかりやすく説明します。Postman Tokyo Meetup 2023.11での発表資料です。

Transcript

1. All rights reserved by Postman Inc Postman API ネットワーク を使って API を公開しよう 草薙 昭彦 テクノロジーエバンジェリスト #PostmanMeetup
2. テクノロジーエバンジェリスト Postman 株式会社 草薙 昭彦 @postman_japan @nagix
3. 提供者・利用者間 コラボレーション API 提供者 コラボレーション API 利用者 コラボレーション API ライフサイクル @postman_japan
4. Postman API プラットフォーム モニター モックサーバー API テスト ドキュメント作成 コレクション API ネットワーク (private/public/partner) ソースコード バージョン管理システム API 設計 SPEC の生成 POSTMAN に SPEC をインポート 双方向の同期 API ビルダー SPEC の設計 標準ルールの適用 静的解析ルールの適用 ポリシー制御とその自動化 POSTMAN アセット の自動生成 CI/CD 自動 API テスト API の デプロイ API デプロイ先環境 Postman CLI モニタリング 連携 POSTMAN アセット へのアクセスと生成 利用者 VS Code ブラウザ アプリ トリガー @postman_japan ワークスペースを通じた共有とコラボレーション 社内だけでなくパートナー、社外との共同作業 API の採用を促進 開発者体験向上 プロダクトリリースのリードタイム短縮化
5. Postman API ネットワーク @postman_japan プライベート API ネットワーク パブリック API ネットワーク • チームメンバーに限定 • チーム内の機能重複の排除 • API 知見やノウハウの共有 • チーム内の API 利用動向の把握 • 多くの利用者・開発者に知ってもらう • 利用者の Time To First Call の短縮 • 利用者からのフィードバックと改善
6. Postman API ネットワーク @postman_japan プライベート API ネットワーク パブリック API ネットワーク • チームメンバーに限定 • チーム内の機能重複の排除 • API 知見やノウハウの共有 • チーム内の API 利用動向の把握 • 多くの利用者・開発者に知ってもらう • 利用者の Time To First Call の短縮 • 利用者からのフィードバックと改善 本日は特にこちらの話
7. パブリック API ネットワーク パブリック API ネットワークは、あらゆる利用者に公開されている API が含まれるパブリック API 成果物 のカタログです。パブリックワークスペースを通じて組織のパブリック API を簡単に共有したり、 Salesforce、PayPal、Notion のような企業の何千ものパブリック API を発見したりすることができま す。 • 広範な利用者・開発者へのアクセス • 利用者の Time to first call の短縮化 ◦ 利用者は公開されているコレクションを フォークして利用 ◦ 利用者の API テストが容易になる • 利用者からのフィードバックと改善 @postman_japan
8. Postman パブリック API ネットワーク @postman_japan
9. Postman パブリック API ネットワーク @postman_japan Explore カタログのトップページ Spotlight Postman おすすめの項目 • おすすめカテゴリー • 新着ワークスペース、コレクション • 今日の人気項目 • 今週の人気項目 • イチ押しカテゴリーの項目 • Postman Flows ギャラリー Trending APIs 今週の人気ワークスペース、コ レクション Collections おすすめコレクション、今週の人気コレク ション、コレクション一覧 Workspaces おすすめワークスペース、 ワークスペース一覧 Flows フロー一覧 Categories カテゴリー一覧
10. Postman パブリック API ネットワーク @postman_japan フォーク回数 ユーザーが自分のワークスペースにフォークを作成し た数 ウォッチ数 変更を追跡しているユーザーの数 ワークスペース・コレクション概要 ワークスペース・コレクションの説明 トレンドバッジ 過去 1 週間に多くのフォークがある時 人気の指標
11. パブリック API ネットワーク内を検索するには？ @postman_japan
12. 検索対象をパブリック API ネットワークに限定 @postman_japan Postman 全体 （自分がアクセスできるすべてのワークスペース） 自分のパーソナルワークスペース、または自分 の所属しているチームのワークスペース 自分の所属しているチームのプライベート API ネットワーク内のワークスペース パブリック API ネットワーク内の ワークスペース
13. さらに検索対象コンポーネントを絞り込み @postman_japan ワークスペース、コレクション、リクエスト、API、フ ロー、チームを絞り込める
14. 公開すると便利な API コンポーネント ワークスペース コレクション API (API ビルダー) Postman の API 開発・テスト作業に必要なツールへの共有アクセスをチームや世 界に提供するコラボレーションハブ OpenAPI、GraphQL、RAML などの幅広い形式で API を共同で設計およ び定義できるツール API リクエストのグループ。コレクションのリクエスト（グループ）の文書化、 テスト、モック、監視を可能。利用者はフォークが可能 環境 フロー @postman_japan よく使う値を格納する変数のセット。システムの環境ごとに作成することで 効率的な切り替えが可能に API の呼び出しフローを GUI でつないで、アプリをビジュアルに構築できる Postman Flows のコンポーネント
15. ワークスペースとは？ ワークスペース内のコレクション、API 定義、環境、モック、モニターなどへの共有アクセスをチームや世界 に提供し、組織や世界をまたいだシームレスなコラボレーションを支援する コラボレーションハブ ワークスペース（パブリック） ワークスペース内の コレクション群 ワークスペース コレクション API (API ビルダー) 環境 フロー @postman_japan
16. ワークスペースとは？ 5 種類のワークスペースがあり、それぞれ異なる共有アクセスレベルを提供します パーソナル 自分だけがアクセス可能 プライベート ワークスペース作成ユーザーとそのワークスペースに招待されたチー ムメンバーのみアクセス可能。要有償プラン チーム 全てのチームメンバーだけがアクセス可能。設定可能なチームメン バー数はプランによって変わる（無料は 3 名まで） パートナー ワークスペース作成ユーザーとそのワークスペースに招待されたチー ムメンバー、およびパートナーとして招待した外部ユーザーのみアクセ ス可能。要 Enterprise Ultimate プラン パブリック 世界中の誰もがアクセス可能。パブリック API ネットワークに API を公 開するにはワークスペースをパブリックする必要がある ワークスペースの種類 @postman_japan
17. ワークスペースとは？ 5 種類のワークスペースがあり、それぞれ異なる共有アクセスレベルを提供します パーソナル 自分だけがアクセス可能 プライベート ワークスペース作成ユーザーとそのワークスペースに招待されたチー ムメンバーのみアクセス可能。要有償プラン チーム 全てのチームメンバーだけがアクセス可能。設定可能なチームメン バー数はプランによって変わる（無料は 3 名まで） パートナー ワークスペース作成ユーザーとそのワークスペースに招待されたチー ムメンバー、およびパートナーとして招待した外部ユーザーのみアクセ ス可能。要 Enterprise Ultimate プラン パブリック 世界中の誰もがアクセス可能。パブリック API ネットワークに API を公 開するにはワークスペースをパブリックする必要がある ワークスペースの種類 @postman_japan
18. コレクションとは？ コレクションは、実行可能な関連 API リクエスト（群）の集合です。コレクション単位で（もしくはコレクション に関連付けて）モックサーバー、モニター、テストスイートなど主要な Postman 機能が利用できます コレクション APIリクエスト テスト サンプル APIリクエスト テスト サンプル APIリクエスト テスト サンプル コレクションでできる主なこと • 複数 API リクエスト、関連レスポンス、テストの定義 • ワークフロー定義（リクエスト呼び出しのシーケンス） • リクエスト・テスト実行の自動化（コレクションランナー活用） • コレクション単位の文書化 • モックサーバー利用（コレクション単位） • モニター利用（コレクション単位） • チームメイトや利用者とのコラボレーション ◦ フォーク (Fork) ◦ プルリクエスト ◦ コメント @postman_japan
19. コレクションとは？ コレクション フォルダー API リクエスト @postman_japan
20. フォークとは？ フォークとは、親要素の別ワークスペースへのコピーであり、親要素に変更を加えることなく変更できる新 しいインスタンスのことです。Postman では、コレクション、環境、フロー (Postman Flows) をフォークで きます。フォークは Postman における API コラボレーションを促進する、利用者・提供者の両方にとって 便利な機能です。 親コレクション 子コレクション ② 親コレクションの 更新・変更に関する通知 ① フォーク ③ 親要素に対してフィードバック • コメント • プルリクエスト フォークにより • 利用者は Time to first call が短縮化できる • 提供者は利用者からフィードバックが得られ る @postman_japan
21. パブリック API ネットワークへの公開ステップ How to Set Up Your First Public Workspace in 5 Easy Steps https://blog.postman.com/how-to-set-up-public-workspaces/ @postman_japan ワークスペースの作成 API 仕様のインポート （オプション） コレクションの追加 API ビルダーで API 設計 （オプション） 環境の追加 ドキュメントの編集 モックの追加 モニターの追加 チームプロフィールの編集 パブリックワークスペースに変更 最初は Personal、Team、Private などでOK
22. API ドキュメントに含めておきたい情報 認証に関する説明 • 利用可能な認証方法についての明確な説明と、認証資格情報の取得と使用に関する徹底したステップ・バイ・ステップの手 順など すべてのエンドポイント、操作、リソースに関する詳細な情報 • パラメータ、ヘッダ、リクエストボディとレスポンスボディを含む、すべての API エンドポイントと操作の包括的な概要情報。ま た、必要な属性やデフォルト値、最小値、最大値など、関連するデータモデルの説明 リクエストとレスポンスの例 • 利用者のエンドポイントの動作理解と、遭遇するかもしれない問題のトラブルシューティングに役に立つ 利用規約 • API のデータと機能が消費者によって悪用されないようにするための法的合意。 API のレート制限に関する情報などは含めるべき。これは、消費者が一定期間内に何回 API を呼び出すことができるかを規 定するものであり、API をサービス拒否 (DoS) 攻撃や、API のパフォーマンスに悪影響を及ぼす可能性のあるその他の行 為から保護するのに役立つ What should be included when creating API documentation?　https://www.postman.com/api-platform/api-documentation/ @postman_japan
23. The Good Documentation Checklist Postman 活用シナリオで良い API ドキュメントにするためのチェックリスト https://www.postman.com/postman/workspace/published-postman-templates/collection/1559645-4b520b0d-cf53-41be-8d24-0e0136416091 @postman_japan
24. 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/ @postman_japan
25. TTFC を短くするには？ @postman_japan パブリック API ネットワークへの公開 認証に必要な情報をまとめ、変数を用意 Web サイトで Run in Postman ボタンを利用 ドキュメントを分かりやすくしサンプルを用意
26. PayPal、Postman で TTFC を 1 分に短縮 @postman_japan 成果 • API コレクションを発見してからそれを呼び 出して肯定的なレスポンスを得るまでの時 間が短縮 • 開発者はこれまで以上に迅速にビジネス価 値を実現 • PayPal API の人気は指数関数的に増加、 PayPal パブリック Postman コレクションの フォーク数は 30,000 を突破 • PayPalは現在、Postman プラットフォーム を使用している数百万人の開発者にリーチ することが可能
27. パブリック API ネットワークへの 登録をお待ちしています！ @postman_japan みんなで Made in Japan の API カタログを充実させていこう！ 日本語検索対応 2023/9 中より対応しました NEW
28. ダウンロードして無料でスタート！ https://www.postman.com/downloads/ デスクトップアプリ • Windows • Mac • Linux Web アプリ • アカウント登録で同 じ機能をブラウザで も利用できる @postman_japan
29. @postman_japan ご清聴いただき、ありがとうございました