Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

草薙昭彦
November 08, 2023

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

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

草薙昭彦

November 08, 2023
Tweet

More Decks by 草薙昭彦

Other Decks in Technology

Transcript

  1. All rights reserved by Postman Inc
    Postman API ネットワーク
    を使って API を公開しよう
    草薙 昭彦
    テクノロジーエバンジェリスト
    #PostmanMeetup

    View full-size slide

  2. テクノロジーエバンジェリスト
    Postman 株式会社
    草薙 昭彦
    @postman_japan
    @nagix

    View full-size slide

  3. 提供者・利用者間
    コラボレーション
    API 提供者
    コラボレーション
    API 利用者
    コラボレーション
    API ライフサイクル
    @postman_japan

    View full-size slide

  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 の採用を促進
    開発者体験向上
    プロダクトリリースのリードタイム短縮化

    View full-size slide

  5. Postman API ネットワーク
    @postman_japan
    プライベート API ネットワーク
    パブリック API ネットワーク
    ● チームメンバーに限定
    ● チーム内の機能重複の排除
    ● API 知見やノウハウの共有
    ● チーム内の API 利用動向の把握
    ● 多くの利用者・開発者に知ってもらう
    ● 利用者の Time To First Call の短縮
    ● 利用者からのフィードバックと改善

    View full-size slide

  6. Postman API ネットワーク
    @postman_japan
    プライベート API ネットワーク
    パブリック API ネットワーク
    ● チームメンバーに限定
    ● チーム内の機能重複の排除
    ● API 知見やノウハウの共有
    ● チーム内の API 利用動向の把握
    ● 多くの利用者・開発者に知ってもらう
    ● 利用者の Time To First Call の短縮
    ● 利用者からのフィードバックと改善
    本日は特にこちらの話

    View full-size slide

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

    View full-size slide

  8. Postman パブリック API ネットワーク
    @postman_japan

    View full-size slide

  9. Postman パブリック API ネットワーク
    @postman_japan
    Explore
    カタログのトップページ
    Spotlight
    Postman おすすめの項目
    ● おすすめカテゴリー
    ● 新着ワークスペース、コレクション
    ● 今日の人気項目
    ● 今週の人気項目
    ● イチ押しカテゴリーの項目
    ● Postman Flows ギャラリー
    Trending APIs
    今週の人気ワークスペース、コ
    レクション
    Collections
    おすすめコレクション、今週の人気コレク
    ション、コレクション一覧
    Workspaces
    おすすめワークスペース、
    ワークスペース一覧
    Flows
    フロー一覧
    Categories
    カテゴリー一覧

    View full-size slide

  10. Postman パブリック API ネットワーク
    @postman_japan
    フォーク回数
    ユーザーが自分のワークスペースにフォークを作成し
    た数
    ウォッチ数
    変更を追跡しているユーザーの数
    ワークスペース・コレクション概要
    ワークスペース・コレクションの説明
    トレンドバッジ
    過去 1 週間に多くのフォークがある時
    人気の指標

    View full-size slide

  11. パブリック API ネットワーク内を検索するには?
    @postman_japan

    View full-size slide

  12. 検索対象をパブリック API ネットワークに限定
    @postman_japan
    Postman 全体
    (自分がアクセスできるすべてのワークスペース)
    自分のパーソナルワークスペース、または自分
    の所属しているチームのワークスペース
    自分の所属しているチームのプライベート
    API ネットワーク内のワークスペース
    パブリック API ネットワーク内の
    ワークスペース

    View full-size slide

  13. さらに検索対象コンポーネントを絞り込み
    @postman_japan
    ワークスペース、コレクション、リクエスト、API、フ
    ロー、チームを絞り込める

    View full-size slide

  14. 公開すると便利な API コンポーネント
    ワークスペース
    コレクション
    API (API ビルダー)
    Postman の API 開発・テスト作業に必要なツールへの共有アクセスをチームや世
    界に提供するコラボレーションハブ
    OpenAPI、GraphQL、RAML などの幅広い形式で API を共同で設計およ
    び定義できるツール
    API リクエストのグループ。コレクションのリクエスト(グループ)の文書化、
    テスト、モック、監視を可能。利用者はフォークが可能
    環境
    フロー
    @postman_japan
    よく使う値を格納する変数のセット。システムの環境ごとに作成することで
    効率的な切り替えが可能に
    API の呼び出しフローを GUI でつないで、アプリをビジュアルに構築できる
    Postman Flows のコンポーネント

    View full-size slide

  15. ワークスペースとは?
    ワークスペース内のコレクション、API 定義、環境、モック、モニターなどへの共有アクセスをチームや世界
    に提供し、組織や世界をまたいだシームレスなコラボレーションを支援する
    コラボレーションハブ
    ワークスペース(パブリック)
    ワークスペース内の
    コレクション群
    ワークスペース
    コレクション
    API (API ビルダー)
    環境
    フロー
    @postman_japan

    View full-size slide

  16. ワークスペースとは?
    5 種類のワークスペースがあり、それぞれ異なる共有アクセスレベルを提供します
    パーソナル 自分だけがアクセス可能
    プライベート ワークスペース作成ユーザーとそのワークスペースに招待されたチー
    ムメンバーのみアクセス可能。要有償プラン
    チーム 全てのチームメンバーだけがアクセス可能。設定可能なチームメン
    バー数はプランによって変わる(無料は 3 名まで)
    パートナー ワークスペース作成ユーザーとそのワークスペースに招待されたチー
    ムメンバー、およびパートナーとして招待した外部ユーザーのみアクセ
    ス可能。要 Enterprise Ultimate プラン
    パブリック 世界中の誰もがアクセス可能。パブリック API ネットワークに API を公
    開するにはワークスペースをパブリックする必要がある
    ワークスペースの種類
    @postman_japan

    View full-size slide

  17. ワークスペースとは?
    5 種類のワークスペースがあり、それぞれ異なる共有アクセスレベルを提供します
    パーソナル 自分だけがアクセス可能
    プライベート ワークスペース作成ユーザーとそのワークスペースに招待されたチー
    ムメンバーのみアクセス可能。要有償プラン
    チーム 全てのチームメンバーだけがアクセス可能。設定可能なチームメン
    バー数はプランによって変わる(無料は 3 名まで)
    パートナー ワークスペース作成ユーザーとそのワークスペースに招待されたチー
    ムメンバー、およびパートナーとして招待した外部ユーザーのみアクセ
    ス可能。要 Enterprise Ultimate プラン
    パブリック 世界中の誰もがアクセス可能。パブリック API ネットワークに API を公
    開するにはワークスペースをパブリックする必要がある
    ワークスペースの種類
    @postman_japan

    View full-size slide

  18. コレクションとは?
    コレクションは、実行可能な関連 API リクエスト(群)の集合です。コレクション単位で(もしくはコレクション
    に関連付けて)モックサーバー、モニター、テストスイートなど主要な Postman 機能が利用できます
    コレクション
    APIリクエスト
    テスト サンプル
    APIリクエスト
    テスト サンプル
    APIリクエスト
    テスト サンプル
    コレクションでできる主なこと
    ● 複数 API リクエスト、関連レスポンス、テストの定義
    ● ワークフロー定義(リクエスト呼び出しのシーケンス)
    ● リクエスト・テスト実行の自動化(コレクションランナー活用)
    ● コレクション単位の文書化
    ● モックサーバー利用(コレクション単位)
    ● モニター利用(コレクション単位)
    ● チームメイトや利用者とのコラボレーション
    ○ フォーク (Fork)
    ○ プルリクエスト
    ○ コメント
    @postman_japan

    View full-size slide

  19. コレクションとは?
    コレクション
    フォルダー
    API リクエスト
    @postman_japan

    View full-size slide

  20. フォークとは?
    フォークとは、親要素の別ワークスペースへのコピーであり、親要素に変更を加えることなく変更できる新
    しいインスタンスのことです。Postman では、コレクション、環境、フロー (Postman Flows) をフォークで
    きます。フォークは Postman における API コラボレーションを促進する、利用者・提供者の両方にとって
    便利な機能です。
    親コレクション
    子コレクション
    ② 親コレクションの
    更新・変更に関する通知
    ① フォーク
    ③ 親要素に対してフィードバック
    ● コメント
    ● プルリクエスト
    フォークにより
    ● 利用者は Time to first call が短縮化できる
    ● 提供者は利用者からフィードバックが得られ

    @postman_japan

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  25. TTFC を短くするには?
    @postman_japan
    パブリック API ネットワークへの公開
    認証に必要な情報をまとめ、変数を用意 Web サイトで Run in Postman ボタンを利用
    ドキュメントを分かりやすくしサンプルを用意

    View full-size slide

  26. PayPal、Postman で TTFC を 1 分に短縮
    @postman_japan
    成果
    ● API コレクションを発見してからそれを呼び
    出して肯定的なレスポンスを得るまでの時
    間が短縮
    ● 開発者はこれまで以上に迅速にビジネス価
    値を実現
    ● PayPal API の人気は指数関数的に増加、
    PayPal パブリック Postman コレクションの
    フォーク数は 30,000 を突破
    ● PayPalは現在、Postman プラットフォーム
    を使用している数百万人の開発者にリーチ
    することが可能

    View full-size slide

  27. パブリック API ネットワークへの
    登録をお待ちしています!
    @postman_japan
    みんなで Made in Japan の API カタログを充実させていこう!
    日本語検索対応
    2023/9 中より対応しました
    NEW

    View full-size slide

  28. ダウンロードして無料でスタート!
    https://www.postman.com/downloads/
    デスクトップアプリ
    ● Windows
    ● Mac
    ● Linux
    Web アプリ
    ● アカウント登録で同
    じ機能をブラウザで
    も利用できる
    @postman_japan

    View full-size slide

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

    View full-size slide