Postman Collectionを使って社内外とのAPI連携開発・コラボレーションを円滑にできたお話

Postman Tokyo Meetup 2023.8 発表資料
https://postman.connpass.com/event/287138/

私の会社ではグローバルチームでWeb API連携のためのソフトウェアを開発しているのですが、そのプロジェクトでPostmanが持つコラボレーション機能「Postman Collection」を活用して、プロジェクトの摩擦を軽減することができました。
このセッションではそんな便利なPostmanのコラボレーション機能にフォーカスしながら、Postman Collectionとは何か？ Postman Collectionの仕組みや仕様、自動生成・共有・活用方法などについてお話します。

Transcript

1. © 2023 CData Software Japan, LLC | www.cdata.com/jp Postman Collection を使って 社内外とのAPI連携開発・コラボレーションを円滑にできたお話 2023/08/08 Postman Tokyo Meetup 2023.8 CData Software Japan Kazuya Sugimoto
2. © 2023 CData Software Japan, LLC | www.cdata.com/jp CData Software Japan の Lead Engineer これまで300種類以上のAPIを見たり触ったりしている API中毒な人。 Twitter：@sugimomoto Facebook：sugimomoto Blog：https://www.cdatablog.jp/ About Speaker Software Design 2023年8月号 Web API 特集 の第1章「Web APIの目的と技術要素 利用者／提供者の利点や技術的なしくみをひも 解く」を執筆 https://gihyo.jp/magazine/SD/archive /2023/202308
3. 3 本社：US(NC州), オフィス：日本 / 欧州 / インド / 中国 エンタープライズ・開発者・データサイエンティスト向けの “real-time data connectivity” ソフトウェアのリーダー 日本法人 : CData Software Japan 合同会社 本社：宮城県仙台市 設立：2016/06 〜 © 2023 CData Software Inc. — CONFIDENTIAL – DO NOT DUPLICATE OR DISTRIBUTE CData Software EMPLOYEES 400+ ACTIVE CUSTOMERS 10,000+ OEM PARTNERS 180+
4. © 2023 CData Software Japan, LLC | www.cdata.com/jp 1. About CData Software 今日のお話
5. © 2023 CData Software Japan, LLC | www.cdata.com/jp CRMおよびマーケティング自動化 会計システム コラボレーションおよびERP オンプレミスおよびクラウドDB ドキュメントおよびファイル形式 ソーシャルネットワーキング ネットワーキングおよび認証 電子商取引 その他 CData Software は様々なツール・サービス APIの接続先を 拡張するドライバー・コネクター製品を扱っている会社 https://www.cdata.com/jp/drivers/
6. © 2023 CData Software Japan, LLC | www.cdata.com/jp Backlog API と簡単に連携できる CData Drivers for Backlog を提供しています！ https://www.cdata.com/jp/drivers/backlog/ 今回はこの Backlog Driver開発時のお話 「API連携製品の開発プロジェクト」におけるコミュニケー ション・コラボレーションを円滑に進める上で Postman をどのように活用したのか？
7. © 2023 CData Software Japan, LLC | www.cdata.com/jp DEMO
8. © 2023 CData Software Japan, LLC | www.cdata.com/jp 1. About CData Software 「API連携製品の開発プロジェクト」における コミュニケーション・コラボレーションの課題
9. © 2023 CData Software Japan, LLC | www.cdata.com/jp 1 Chome-6-27 Chuo, Aoba Ward, Sendai, Miyagi Prefecture 980-0021, Japan Tel: 050-5578-7390 CData Japan 600 Market St. #300 Chapel Hill, NC 27516 USA Tel: (919) 885-0202 Fax: (919) 928-5455 US Headquarters - United Kingdom - Central & Eastern Europe - Central China Additional Offices CData の開発体制 日本の SaaS API Drivers もグローバルで開発 デザインは日本チーム、開発はアルバニアチーム、QAはインドチーム ドキュメントはUSチーム、リリース作業は中国チーム、みたいなことが起こる
10. © 2023 CData Software Japan, LLC | www.cdata.com/jp すべて自社コードで実装 既存のSDK・ライブラリを使わない ちなみに、Backlog APIは 公式・非公式含めて とてもライブラリが充実している https://developer.nulab.com/ja/docs/backlog/libraries/#
11. © 2023 CData Software Japan, LLC | www.cdata.com/jp Backlog API めちゃくちゃ機能が多い問題 （現在150種類近く） しかも CData Driverは汎用コネ クタなので、ほとんどのAPI機能を 網羅・使っている
12. © 2023 CData Software Japan, LLC | www.cdata.com/jp API Request の共有大変！ 一つ一つ試すのも大変！ POST /api/v2/users?apiKey=XXXXX HTTP/1.1 Host: XXXXX.backlog.com Content-Type: application/x-www-form-urlencoded Content-Length: 70 userId=<文字列>&password=<文字列>&name=<文字列 >&mailAddress=<文字列>&roleType=<数値> POST /api/v2/projects?apiKey=XXXXX HTTP/1.1 Host: XXXXX.backlog.com Content-Type: application/x-www-form-urlencoded Content-Length: 128 name=<文字列>&key=<文字列>&chartEnabled=<真偽値 >&projectLeaderCanEditProjectLeader=<真偽値 >&subtaskingEnabled=<真偽値>&textFormattingRule=<文字 列>
13. © 2023 CData Software Japan, LLC | www.cdata.com/jp なので
14. © 2023 CData Software Japan, LLC | www.cdata.com/jp どれだけスムーズに仕様を共有できるか？ 問題・課題の再現をスピーディに実施できるか？ 同じ環境・リクエストを簡単に実施できるか？ といったことがとても重要 一つ一つは小さい摩擦でも 最終的に大きなコストにつながる
15. © 2023 CData Software Japan, LLC | www.cdata.com/jp CData Driver デザインと合わせて Postman Collection で API 仕様を共有し開発しよう！
16. © 2023 CData Software Japan, LLC | www.cdata.com/jp 1. About CData Software Postman Collection とは？
17. © 2023 CData Software Japan, LLC | www.cdata.com/jp Postman Collection とは何か？ Postman Collections are Executable API Descriptions 実行可能なAPIの記述・Postman Ecosystem の要 APIに関する各種エレメント（リクエスト・レスポンス・ 認証・テストなど）を包括・整理し、Postman を使った APIコラボレーション・開発を促進するための仕様 https://www.postman.com/collection/
18. © 2023 CData Software Japan, LLC | www.cdata.com/jp Postman Collection で何ができるようになるの？ API Publication API Monitoring API Documentation Mock Server Debug Automated Testing https://www.postman.com/collection/ Postman が提供するAPIの検証・モック開発・モニタリング・テスト・ドキュ メンテーションといった一連のコラボレーション機能・API開発のサポート機 能を利用するためのベースになっている。 APIの検証のためだけだと、あまり意識しないが、Postman を有効活用してい く上で理解は必須な機能。
19. © 2023 CData Software Japan, LLC | www.cdata.com/jp 1. About CData Software Postman Collection の仕様
20. © 2023 CData Software Japan, LLC | www.cdata.com/jp Postman Collection は JSON で定義されている https://schema.postman.com/ Postman Collection の仕様は JSON Schema と共にパブリック に公開されている
21. © 2023 CData Software Japan, LLC | www.cdata.com/jp シンプルな構造で結構手軽に作ることができる https://learning.postman.com/collection-format/reference/request/
22. © 2023 CData Software Japan, LLC | www.cdata.com/jp 1. About CData Software Postman Collection を作ってみよう！
23. © 2023 CData Software Japan, LLC | www.cdata.com/jp Postman Collection は 様々なフォーマットから自動生成可能 https://learning.postman.com/docs/designing-and-developing-your-api/importing- an-api/#supported-api-definitions-formats
24. © 2023 CData Software Japan, LLC | www.cdata.com/jp ただし、Backlog API は Open API / Swagger Spec などは未提供 SDKとHTMLベースの API仕様書のみ （問い合わせました）
25. © 2023 CData Software Japan, LLC | www.cdata.com/jp Backlog API 全部登録するのはさすがに大変・・・
26. © 2023 CData Software Japan, LLC | www.cdata.com/jp そこで・・・
27. © 2023 CData Software Japan, LLC | www.cdata.com/jp Backlog API Reference を元に 自動生成する仕組みを構築 .NET C#で Backlog API Referenceをスクレイピング Postman Collectionの JSONを生成して取り込み JSON
28. © 2023 CData Software Japan, LLC | www.cdata.com/jp できあがった Backlog Postman Collection 全機能を名前で検索 一覧可能 DescriptionやReferenceに もすぐに飛べる クエリパラメータ・リクエストBody を簡単に選べる・入力できる
29. © 2023 CData Software Japan, LLC | www.cdata.com/jp Postman Collection を作成したことによる効能 ・開発チームとの仕様の摺合せ・共有がスムーズに。 ・QAやドキュメントチームからの仕様の確認・共同での動作確認などが少なく。 ・エラーハンドリングなどの再現・共有が円滑に。 ・オフラインテストのためのモックデータの作成が簡単に。
30. © 2023 CData Software Japan, LLC | www.cdata.com/jp 1. About CData Software Postman Collection におけるコラボレーション
31. © 2023 CData Software Japan, LLC | www.cdata.com/jp 作成したPostman Collection は 簡単にチームで共有可能 https://learning.postman.com/docs/collaborating-in-postman/private-api-network/adding-private-network/ Workspace に招待して コラボレーション Private API Network で APIカタログを会社・組織で共有
32. © 2023 CData Software Japan, LLC | www.cdata.com/jp Postman Public API Network で世界中に公開も可能 各種API エコシステムを支援 https://www.postman.com/explore 日本ではBtoB ECサービスの BカートがPostman Collection を公開中 https://docs.api.bcart.jp/
33. © 2023 CData Software Japan, LLC | www.cdata.com/jp backlog Postman Collection はGithub で公開中 https://github.com/sugimomoto/backlogPostmanCollection
34. © 2023 CData Software Japan, LLC | www.cdata.com/jp 1. About CData Software まとめ
35. © 2023 CData Software Japan, LLC | www.cdata.com/jp どれだけスムーズに仕様を共有できるか？ 問題・課題の再現をスピーディに実施できるか？ 同じ環境・リクエストを簡単に実施できるか？ といったことがとても重要 一つ一つは小さい摩擦でも 最終的に大きなコストにつながる
36. © 2023 CData Software Japan, LLC | www.cdata.com/jp Postman Collection を最大限活用して API 連携・開発をスムーズにしていきましょう！