PublicAPI開発チームのPostman利用方法

参考になった

会員限定コンテンツです。無料登録すると制限なしでお読みいただけます。

無料登録してアーキテクチャを見る

レビュー投稿日の情報になります

フリー株式会社 / Saaya Murakami (prpr)

メンバー / バックエンドエンジニア

最終更新日2024/08/06投稿日2024/08/06

利用プラン	利用機能	ツールの利用規模	ツールの利用開始時期	事業形態
Freeプラン	Collection, Environment, Pre-request Script	10名以下	2022年7月	B to B

利用プラン	Freeプラン
利用機能	Collection, Environment, Pre-request Script
ツールの利用規模	10名以下
ツールの利用開始時期	2022年7月
事業形態	B to B

アーキテクチャ

会員限定コンテンツ無料登録してアーキテクチャを見る

アーキテクチャの意図・工夫

Collectionの更新は、APIスキーマを新しく更新するタイミングで行っています。PostmanAPIを利用して自動化しているため、普段の開発で意識せずとも、Collectionが最新化されます。
参考：OpenAPIを元にしたPostmanCollectionの作成・更新を自動化する方法

導入の背景・解決したかった問題

導入背景

freee Public APIの開発

freee Public APIでは複数のプロダクトドメインのAPIが提供されており、またそれぞれのエンドポイント数も多いもので30種類以上の数を提供させていただいています。API開発はWEB機能を開発する各チームに一緒に担ってもらいつつ、API基盤チームで各チームでの開発のサポートやPublicAPI全体の品質の管理をしています。

ツール導入前の課題

①複数APIのリクエストを行うのが大変　
開発・テスト・調査のそれぞれのシーンにおいて何種類ものAPIを頻繁にcallするため、API呼び出しを効率的に行うツールが必要でした。

②環境の切り替え
freee Public APIはOAuth2.0を採用していますので、API呼び出しのためにアクセストークンが必要になります。開発メンバーにおいては開発環境・検証環境・ステージング環境・本番の環境を行き来しながら開発・テストを行いますので、それぞれの環境にクライアントアプリを作成しアクセストークンを取得後、それを利用してAPI呼び出しを行う必要があります。curl等で各環境の設定情報をいちいち手動で書き換えるのは大変でした。

③APIスキーマの最新化
curlなどで自分でAPIのrequest情報を設定している場合、APIのスキーマが変わった場合にリクエストが失敗してしまうし、スキーマと照らし合わせながらrequestの修正をしないといけませんでした。

どのような状態を目指していたか

以下の状態を理想と考えました

複数プロダクトドメインのAPI群を管理し、複数のAPIを効率よくcallすることができる
最新スキーマを取り込んで常に最新のスキーマ定義でAPIリクエストを行える
環境ごとの設定を保存でき、簡単にAPIをcallする環境をswitchingできる

比較検討したサービス

curl
Thunder Client (VSCode拡張機能)

比較した軸

GUIで簡単に操作できること
複数のAPIかつ複数環境のリクエストを効率よく行えること
最新スキーマで常にリクエストができること

選定理由

GUIのAPIクライアントツールとしてデファクトスタンダードであること
Collectionという単位でプロダクトドメインごとのAPI群を管理できる＆環境変数で環境ごとの設定を切り替えられること
Collectionをforkすることができ、originalが更新されるとその内容をfork先に反映できること（コラボレーション）

導入の成果

改善したかった課題はどれくらい解決されたか

先にあげた課題はすべて解決されました。

どのような成果が得られたか

①課題が解決されて、メンバーの開発効率が上がった
複数プロダクトドメインにまたがるAPIをとても簡単にcallできるようになり、開発効率がかなりあがったと感じています。特に環境のswitchingはとても楽になったと開発を担うメンバーからフィードバックを頂いています。

②ユーザーにもCollectionを使ってもらえるようになった
これは副作用的なところなのですが、fork元のCollectionとしてPostmanのAPIネットワークにfreee Public APIのCollectionを公開しました(2024年7月にPostmanからの公式認定もいただきました)。こちらは全世界に向けて公開されるものなので社内だけでなくユーザーさんにもCollectionを使っていただける状態になりました。
実はCollection公開以前にもPostmanを用いてfreee Public APIを利用してくれているユーザーさんがいたのですが、その時点のスキーマを自身で取り込んでいただく方法だったため最新スキーマに追従できない問題がありました。公式としてPostmanCollectionを提供することでこの問題も解決することができました。

導入時の苦労・悩み

ツール自体はとても使いやすいGUIで、Collectionも弊社が公開スキーマとして提供しているOpenAPIのyamlファイルをimportすることで作成できるため導入時の苦労点はありませんでした。

現在の悩みとしてはより詳しく機能を知りたい場合にDocumentが英語しかなくキャッチアップに時間がかかることです。昨年Postman日本法人が設立し、日本語Documentも充実させていくとのことなので期待しています。

導入に向けた社内への説明

上長・チームへの説明

Freeプランでの利用だったため、チーム内でカジュアルに利用を初めて利用方法を確立してから、他チームへ展開していきました。

活用方法

よく使う機能

Collection
Environment
Pre-request Script

ツールの良い点

APIネットワークとコラボレーション
コラボレーションとはPostmanが提唱している「開発者、テスター、アーキテクト、その他ビジネス関係者が協力してAPIを作成および利用するプロセス」というもので、ワークスペースやAPIネットワークを駆使することでいろんな方面のコラボレーションを実現できます。特に自社のPublicAPIをAPIネットワークに公開しそこからforkしてすぐにAPIの利用していただけるのはPostmanならではの良い点だと思っています。

- **Pre-request Script**
APIリクエスト実行前に実行するスクリプト作成できます。リクエスト前に各環境の変数を自動的に設定する仕組みを作成して活用しています。
参考：https://speakerdeck.com/freee/freeeapi-x-postman-api-collaboration-to-make-small-business-the-worlds-leading-actor?slide=15

ツールの課題点

Documentなど日本語対応がされていないところが多くある。
より使いこなそうとすると英語のDocumentに当たるので少しキャッチアップが大変です。

ツールを検討されている方へ

PublicAPIだったり、スキーマ駆動なAPI開発をされているチームでの導入であれば本記事が参考になるかもしれません。ご活用ください。
Postman主催のイベントが頻繁に開催されているので、活用すれば効率的にキャッチアップができると思います。

今後の展望

APIドキュメントの運用
弊社管理のリファレンスサイトもあるので要検討ですが、Postmanが提供するAPIのライフサイクルへの理解を深めより提供者・利用者ともに使いやすいAPIドキュメントを目指したいと思います。

- **Postman Flowsの利用**
ノーコードでAPIを使える機能なので、ユーザーさんに簡単にfreee Public APIをお試し頂いたり、開発者ではないユーザーさんの利用に活用頂いたり、APIを組み合わせてこんな事ができるよという事例紹介に使ったりなど、活用の道を模索したいと思っています。

フリー株式会社 / Saaya Murakami (prpr)

メンバー / バックエンドエンジニア

フリー株式会社 API基盤チーム