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

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

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

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

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

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

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 知識がない

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コレクション

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 部門長 / マネージャー

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

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

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

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

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

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

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との同期

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

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

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

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

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

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

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

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

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

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

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

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リリース

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

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よりも堅牢かつ正確。またモック（サーバー） に活用可能

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

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 コレクション インポート

ちなみに、他にも様々なデータソースからの インポートが可能 コレクション 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定義

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/

ありがとうございました