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

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

Yoichi Kawasaki
September 06, 2023

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

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

Yoichi Kawasaki

September 06, 2023
Tweet

More Decks by Yoichi Kawasaki

Other Decks in Technology

Transcript

  1. アジェンダ • APIコラボレーションの現状 • Postmanが支援するAPIコラボレーション ◦ APIコラボレーションのための主要コンポーネント ▪ ワークスペース、コレクション、 APIビルダー

    ▪ Postman APIネットワーク ◦ Postmanを活用したコラボレーション例 ◦ 無料プランでできるコラボレーション • 2つのAPI仕様 ◦ OpenAPI仕様 (OAS) ◦ Postman Collection仕様 ◦ OpenAPI ⇔Postman Collection変換
  2. APIコラボレーションとは? 開発者、テスター、アーキテクト、その他のビジネス関係者が協力して API を作成およ び利用するプロセス APIコラボレーション例 • 内部APIの設計・開発・テストにおける組織内コラボレーション • パートナー向けAPIの特定パートナー・顧客とのコラボレーション

    • パブリックAPIの利用者とのコラボレーション APIコラボレーションの目的 • すべての API が一貫して利用可能で、パフォーマンスが高く、使いやすく、消費者のニーズを満た すことができるようにすること
  3. 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コレクション
  4. APIコラボレーション主要コンポーネント ワークスペース コレクション APIs (APIビルダー) パブリック APIネットワーク プライベート APIネットワーク 組織内の内部APIの利用者と提供者が

    API成果物 を簡単に発見、探索、共有 できる内部APIカタログの構築が可能 パブリックAPI成果物のカタログ。API提供者と世界中の利用者を結びつける世界 最大のハブ PostmanのAPI開発・テスト作業に必要なツールへの共有アクセスをチームに提供 するコラボレーションハブ OpenAPI、GraphQL、RAML などの幅広い形式で API を共同で設計およ び定義できるツール APIリクエストのグループ。コレクションのリクエスト(グループ)の文書化、テ スト、モック、監視を可能。利用者はForkが可能 APIネットワーク
  5. コレクション コレクションは、実行可能な関連APIリクエスト(群)の集合です。コレクション単位で(もしくはコレクションに 関連付けて)モックサーバー、モニター、テストスイートなど主要なPostman機能が利用できます コレクション APIリクエスト テスト サンプル APIリクエスト テスト サンプル

    APIリクエスト テスト サンプル コレクションでできる主なこと • 複数APIリクエスト、関連レスポンス、テストの定義 • ワークフロー定義(リクエスト呼び出しのシーケンス) • リクエスト・テスト実行の自動化(コレクションランナー活用) • コレクション単位の文書化 • モックサーバー利用(コレクション単位) • モニター利用(コレクション単位) • チームメイトや利用者とのコラボレーション ◦ フォーク(Fork) ◦ プルリクエスト ◦ コメント 他にもいろんなことができます
  6. 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との同期
  7. Postman APIネットワーク Postman API ネットワークは、 API 利用者と API 提供者の双方が API

    を簡単に発見、探索、共有でき るユニークな場所を提供します。 Postman API ネットワークには2つの種類があります: パブリック APIネットワーク プライベート APIネットワーク APIネットワーク
  8. 無料プランにおけるコラボレーションの代表的な制約 - チームメンバーは3人まで - 4人以上とデータの共有する場合の代替手法 - Postmanコレクションをファイルにエクスポート→共有→インポートして共有 - コレクションをコード管理システムと同期設定している場合はGitHubなどリポジトリからの参照 も可能

    - プライベートAPIネットワーク活用した組織内の内部API成果物の共有・探索はできない(プライベー トAPIネットワークはEnterpriseプランのみ) プランごとの制限に関して詳細は下記ページを参照ください Postman API Platform plans and pricing https://www.postman.com/pricing/
  9. 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リリース
  10. 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よりも堅牢かつ正確。またモック(サーバー) に活用可能
  11. 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 コレクション インポート
  12. ちなみに、他にも様々なデータソースからの インポートが可能 コレクション 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定義
  13. 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/