意外と知られていないPostmanで実現するAPIコラボレーションの世界 / Postman API Collaboration

Presentation Slides for Postman Tokyo Meetup 2023.9
Session title: 意外と知られていないPostmanで実現するAPIコラボレーションの世界 / Postman API Collaboration
Date: 2023/09/06

Transcript

1. All rights reserved by Postman Inc
   意外と知られていない
   Postmanで実現する
   APIコラボレーションの世界
   川崎庸市
   Postman株式会社
   

   View Slide

2. テクノロジーエバンジェリスト
   Postman 株式会社
   川崎 庸市
   @yokawasa
   

   View Slide

3. アジェンダ
   ● APIコラボレーションの現状
   ● Postmanが支援するAPIコラボレーション
   ○ APIコラボレーションのための主要コンポーネント
   ■ ワークスペース、コレクション、
   APIビルダー
   ■ Postman APIネットワーク
   ○ Postmanを活用したコラボレーション例
   ○ 無料プランでできるコラボレーション
   ● ２つのAPI仕様
   ○ OpenAPI仕様 (OAS)
   ○ Postman Collection仕様
   ○ OpenAPI ⇔Postman Collection変換
   

   View Slide

4. APIコラボレーションとは？
   開発者、テスター、アーキテクト、その他のビジネス関係者が協力して API を作成およ
   び利用するプロセス
   APIコラボレーション例
   ● 内部APIの設計・開発・テストにおける組織内コラボレーション
   ● パートナー向けAPIの特定パートナー・顧客とのコラボレーション
   ● パブリックAPIの利用者とのコラボレーション
   APIコラボレーションの目的
   ● すべての API が一貫して利用可能で、パフォーマンスが高く、使いやすく、消費者のニーズを満た
   すことができるようにすること
   

   View Slide

5. APIコラボレーションの現状
   

   View Slide

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

   View Slide

7. API利用における障壁
   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 時間がない (27%)
   #4 知識がない
   

   View Slide

8. APIでのコラボレーション
   2023 State of the API Report
   https://voyager.postman.com/pdf/2023-state-of-the-api-report-postman.pdf
   #1 コラボレーションツールを活用
   した開発 (50%)
   コラボレーションツール例: Postman
   #2 API成果物のコード管理サービ
   スへの登録・公開 (39%)
   コード管理サービス例: GitHub/GitLab/Bitbucket
   #3 API成果物のURL共有 (39%)
   #4 APIポータルにドキュメントを登
   録・公開
   ※ API成果物例: Swagger、OpenAPI、
   Postmanコレクション
   

   View Slide

9. APIにかかわっている人
   2023 State of the API Report
   https://voyager.postman.com/pdf/2023-state-of-the-api-report-postman.pdf
   #1 フルスタック開発者
   #2 バックエンド開発者
   #3 QAエンジニア
   #4 部門長 / マネージャー
   

   View Slide

10. All rights reserved by Postman Inc
    Postmanが支援する
    APIコラボレーション
    

    View Slide

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

    View Slide

12. APIコラボレーション主要コンポーネント
    ワークスペース
    コレクション
    APIs (APIビルダー)
    パブリック
    APIネットワーク
    プライベート
    APIネットワーク
    組織内の内部APIの利用者と提供者が API成果物 を簡単に発見、探索、共有
    できる内部APIカタログの構築が可能
    パブリックAPI成果物のカタログ。API提供者と世界中の利用者を結びつける世界
    最大のハブ
    PostmanのAPI開発・テスト作業に必要なツールへの共有アクセスをチームに提供
    するコラボレーションハブ
    OpenAPI、GraphQL、RAML などの幅広い形式で API を共同で設計およ
    び定義できるツール
    APIリクエストのグループ。コレクションのリクエスト（グループ）の文書化、テ
    スト、モック、監視を可能。利用者はForkが可能
    APIネットワーク
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

16. APIビルダー
    チームによるAPI設計を支援するツールです。直感的なUIを介してAPIの構造を定義できます
    API Development Overview
    https://learning.postman.com/docs/designing-and-developing-your
    -api/the-api-workflow/
    APIビルダーの主要機能
    ● API設計
    ○ スキーマ定義（インポートも可能）
    ○ API定義のバリデーション
    ○ 定義からサーバーサイドコードの生成
    ○ コレクション、テスト、ドキュメント生成
    ● チーム開発支援
    ○ チーム間のAPI共有
    ○ コメント、Changelog
    ● APIバージョン管理
    ○ コードリポジトリ(GitHub, GitLab,
    Bitbucket, and Azure)と同期 Enterprise Ultimate または Postman for Internal
    API Managementプランのみサポート機能
    ● 4つ以上のAPI定義・管理
    ● ネイティブGitとの同期
    

    View Slide

17. APIビルダー
    APIビルダーがサポート
    するAPI定義形式
    

    View Slide

18. APIビルダー
    API定義の設計・編集
    API定義からコレクション生成
    コード管理システム連携で
    API定義 / コレクション設定
    をリポジトリ同期
    APIバージョンの
    パブリッシュ
    外部サービスとの連携
    ● API Gatewayサービス
    ● APMサービス
    ● CI/CDサービス
    コメント記入
    

    View Slide

19. コード管理システムと連携したOpenAPI仕様と
    Postmanコレクションの更新イメージ
    参考: Latest Updates to Syncing Your Specs with Collections
    https://blog.postman.com/latest-updates-to-syncing-your-specs-with-collections/
    補足
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

25. 無料プランにおけるコラボレーションの代表的な制約
    - チームメンバーは3人まで
    - 4人以上とデータの共有する場合の代替手法
    - Postmanコレクションをファイルにエクスポート→共有→インポートして共有
    - コレクションをコード管理システムと同期設定している場合はGitHubなどリポジトリからの参照
    も可能
    - プライベートAPIネットワーク活用した組織内の内部API成果物の共有・探索はできない（プライベー
    トAPIネットワークはEnterpriseプランのみ）
    プランごとの制限に関して詳細は下記ページを参照ください
    Postman API Platform plans and pricing https://www.postman.com/pricing/
    

    View Slide

26. All rights reserved by Postman Inc
    ２つのAPI仕様:
    OpenAPI仕様 (OAS)と
    Postmanコレクション仕様
    

    View Slide

27. OpenAPI 仕様 (OAS)
    OpenAPI 3.1（ 2021年２月リリース）は、RESTful APIのためのAPI記述形式で、HTTP API機能を人間と
    コンピュータが理解できるようにするためのプログラム言語に依存しない仕様形式。
    info
    OpenAPI Specification 3.1
    servers
    paths
    webhooks
    components
    security
    tags externalDocs
    記述形式：JSON、YAML
    

    View Slide

28. OpenAPIの歴史
    参考: What is OpenAPI ?
    https://blog.postman.com/what-is-openapi/
    2011 2014 2017.7 2021.2
    Swagger 1.0
    リリース
    Swagger 2.0
    リリース
    2015
    Swagger 2.0が
    OpenAPI Initiative
    に寄贈
    OpenAPI 3.0
    リリース
    OpenAPI 3.1
    リリース
    Swagger 2仕様の新しいバージョン と
    してOpenAPI 3リリース
    

    View Slide

29. PostmanはOASの策定に参画しています
    - OAS を APIライフサイクルにおける重要なAPI
    コントラクト（契約）形式と認識
    - OAS策定に参画しAPIエコノミー拡大やそのエ
    コシステムに貢献
    Postman Joins the OpenAPI Initiative
    https://blog.postman.com/postman-joins-openapi-initiative/
    

    View Slide

30. Postmanコレクション仕様
    Postmanコレクションの記述形式。コレクションに含まれるAPIリクエストのAPIエンドポイント、リクエスト、
    レスポンス、テストなどの情報やAPI 呼び出しのシーケンスを定義できます
    info
    items
    event
    variable
    auth
    protocolPofileBehavior
    記述形式：JSON
    Postman Collection v2.1
    ● OAS、PostmanコレクションどちらもAPIのpath、パラメー
    タ、リクエスト、レスポンス情報などのAPIに関する記述は可
    能
    ● OASとPostmanコレクションの大きな違い→ APIライフサイ
    クルに関する情報
    ○ ドキュメント
    ■ コレクション・フォルダーごと
    ○ テスト
    ■ リクエスト前後のスクリプト定義
    ○ ワークフロー
    ■ API呼び出しのシーケンス定義
    ○ サンプル情報
    ■ Open APIよりも堅牢かつ正確。またモック（サーバー）
    に活用可能
    

    View Slide

31. Postmanコレクションのエクスポート
    Postmanコレクション v2もしくは v2.1の形式でエクスポートできます
    Postman
    Collection
    2.0 or 2.1
    エクスポート
    

    View Slide

32. OAS / コレクションのPostmanへのインポート
    OpenAPI 3.0 or 3.1定義 、およびPostmanコレクション v2.0 or v2.1いづれの形式でもインポート可能で
    す。OpenAPI定義は互換性のある範囲でPostmanコクレション形式に変換されます。
    OpenAPI
    3.0 or 3.1
    Postman
    Collection
    2.0 or 2.1
    コレクション
    インポート
    

    View Slide

33. ちなみに、他にも様々なデータソースからの
    インポートが可能
    コレクション
    GitHub
    GitLab
    Importing data into Postman
    https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-data/
    Bitbucket
    Azure Code Repository
    Azure API Management
    AWS API Gateway
    New Relic
    cURL Commands
    OpenAPI
    Postman Collection
    コード管理サービ
    ス
    APIゲートウェイ
    サービス
    APMサービス
    インポート
    RAML
    WSDL
    GraphQL
    API定義
    

    View Slide

34. PostmanコレクションからOAS形式への変換
    PostmanコレクションからOASファイルに変換してくれるOSSツール
    ● postman-to-openapi https://joolfe.github.io/postman-to-openapi/
    ● postman2openapi https://github.com/kevinswiber/postman2openapi
    postman-to-openapiの例
    # Install using npm
    npm i postman-to-openapi -g
    # Convert Postman Collection v2.1 to OpenAPI v3.0
    p2o postman_collection.json -f openapi.yml
    postman2openapi web UIイメージ
    https://kevinswiber.github.io/postman2openapi/
    

    View Slide

35. ありがとうございました
    

    View Slide