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

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も充実させていくとのことなので期待しています。

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

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