🗂

Postmanに法人番号検索REST APIを登録して世界へ公開！

に公開
postmanpostcoderes
tech

3行まとめ

  • この記事は Postman Advent Calendar 2023のシリーズ2、17日目の記事です。
  • Postmanにアカウント登録して既存のREST API 仕様を登録し、Flow、Test、Visualization を使ってみました。
  • 昔は無料でできることが少なかったのですが今は無料で色々できます。

背景

業務で Web アプリケーションを作成しているときに、「こんな Web API があったら楽なのに」と思うことがあり、なければ作ってしまえば良いと思い、個人的に無料で簡単に利用できる REST API によるデータ公開しています。

例えば住所の自動補完に使う郵便番号 API、インボイス登録番号に関連した法人番号検索 API などです。

今回は法人番号検索 API を扱います。

image.png

API は OpenAPI の仕様で公開しています。
https://corporation.teraren.com/openapi/corporation.teraren.com.yml

その API 仕様を redocというJavaScriptライブラリを用いて見やすく表示しています。
https://corporation.teraren.com/doc/redoc

問題

これらのサービス自体はなかなか認知されないです。
そして、開発者がテストで軽く使ってみようとしても CLI からじゃないとテストできなかったり、swagger editor に OpenAPI のファイルを読み込ませてからリクエストを出すと言ったことをしないといけないので利用までの敷居が高いです。

アプローチ

Postman は世界的に広く使われている API 仕様を公開するサービスです。Postman を通じて開発者に広く知ってもらったり、開発者が使いやすい API の状態を作っていきたいと思います。

redoc 仕様公開はいわばドキュメントの公開です。Postman は仕様の公開と実行環境の提供です。

Postmanとは

Postman は API 開発のための強力な SaaS プラットフォームです。

API リクエストの作成、テスト、ドキュメント化、共有を容易にするツールを提供します。Postman は、REST、SOAP、GraphQL などの様々な API タイプに対応し、開発者が API のエンドポイントを簡単に検証できるようにします。

また、環境変数の管理、テストスクリプトの作成、API レスポンスのモニタリングなどの機能も備えており、チームでの協業をサポートするためのチームワークスペースも提供しています。

具体例でいうと、SwitchBotがPostmanでAPIを公開しています。

https://www.postman.com/

PostmanにAPIを登録して設定

ユーザ登録をした上で、API を登録する準備を進めていく手順を紹介します。

初期化

API を登録するためにはワークスペースを作る必要があります。

image.png

API 仕様はパブリックなので public を選びます。

image.png

public にする場合は、自分のプロフィールに公開用の情報を追加する必要があるのでダイアログに出たとおりに設定して OK を押します。

ちなみにこちらが私のプロフィールページになります。
https://www.postman.com/matsubokkuri

OpenAPI のファイルをインポートできる機能があったので早速 import してみます。
image.png

OpenAPIファイルをインポート

どうやってインポートをするか聞かれましたが、デフォルトで進んでみます。

追記: 上の Postman Collection は Postman での標準となる API 仕様のフォーマットです。下の、OpenAPI 3.0 witha Postman Collection は OpenAPI 3.0 との互換性を保った上での API 表現と、Postman 独自の Collection の両方に追加されます。今回は、Postman 専用に不可逆なファイルコンバートとして割り切ります。

image.png

インポートが完了すると左側のメニューに階層化されて表示されました。
image.png

しかしながら、階層が多いように感じたので適切なコレクションを作成して、エンドポイントを適切なコレクションに入れ直しました。ドラッグ&ドロップで移動できるので楽です。
image.png

エンドポイントの名前が見づらかったので少し修正しました。これで API を使う開発者にとってもかなり見やすくなったと思います。
image.png

機能を使ってみる

早速テストで法人番号の一覧を表示する API を呼び出してみます。下のペインに結果が整形されて表示されました。

image.png

Visualization のタブを選ぶと上の JSON の結果がテーブルに勝手に整形されて表示されました。見やすいです。
image.png

グラフ化できるような値の場合はグラフとして表示できるようです。
image.png

仮に line chart で描画してみました。メトリックや集計はできなさそうです。自動で選ばれたメトリックが X と Y に設定されました。自動で作成できるのは楽です。
image.png

一覧の取得はパラメータを一切必要としませんでしたが、今度は 1 つの法人の情報を取得してみます。
変数となる部分は、collection のスコープで定義されているようです。
image.png

左のメニューの一番上のコレクションを選択したら変数の一覧とデフォルト値が表示されました。
image.png

有効な値に変更していきつつ、サーバの URL といった環境依存の変数は Environment に移します。
完成した設定がこちらです。コレクションスコープ。
image.png

こちらは環境スコープです。
image.png

注意点
  • 右上に「Save」ボタンがあるので毎回押し忘れないように気をつけましょう。
  • Current Value のカラムにある値が使われるのでこちらも合わせて正しい値を設定しておきましょう。

ということで、法人の情報を 1 件取得してみます。結果が下のペインに表示されました。
image.png

同様に、他のエンドポイントに対しても適切にパラメータや変数を設定していき、呼び出しができることを確認します。
image.png

APIの自動テスト

API が正常に動作しているか、適切なスキーマで返却されているかをテストできる機能があります。
テストの内容は、コレクション単位、エンドポイント単位で設定できます。

以下の例は、コレクション単位で設定できるテストの部分に書いてあります。
単純に 200 番が返ってくるかどうかをテストするような汎用的な内容です。
image.png

上記を実行すると以下のようになります。各エンドポイントの呼び出しに対して評価されます。
image.png

今度は、個別のエンドポイントでテストを書いてみます。
簡易的に、配列で値が返ってくるかを書いてみます。保存して、下のリフレッシュボタンを押すとテストを実行できます。
image.png

テスト内容は GPT に問い合わせることで半自動に作成でるので楽です。
しかしながら、デバッグ方法がちょっとわかりませんでした。console に出力してもその内容がどこに出るの発見できませんでした。

今度は、コレクションの方に戻って定期的に自動テストを実行するように設定しておきます。これによって、API が仕様通りに動いているかを Postman を見るだけでひと目でわかるようになります。
image.png

このあたりは OpenAPI のスキーマを自動的に読み込んで、自動的にテストを書いてほしいものです。

monitorの設定

外部監視が設定できます。

image.png

定期的にテストを実行して死活監視してくれるようです。
image.png

Flowの作成

Postman 上で API や計算処理をしてワークフローを構築できるサービスです。

法事番号検索 API では、各都道府県ごとの法人数を返却するエンドポイントがあるのでシンプルですがグラフ化してみます。

ものの 2 分でグラフが構築できました。簡易的なダッシュボードとしても使えそうです。

image.png

プロフィールの整備

最後にプロフィールを入力しておきます。
デフォルトのアイコンが何を意味しているのかよくわからないので写真も設定しておきました。

image.png

こんな感じで表示されました。かっこ良いです！
image.png
https://www.postman.com/matsubokkuri

考察

API仕様の提供方法

今まで使っていた Open API と Postman は同じレイヤのプロダクトなのでどちらをメインにして運用するかは考えどころです。→追記:GitHub 上の OpenAPI ファイルと Postman 上の仕様を同期できる機能があります。

Open API で書いておけば committeeといったライブラリで自動的にリクエストとレスポンスのテストを行ってくれるのでこれはかなり重宝します。→追記:Postmanでも型をチェックしてくれます。しかし、エラーメッセージが抽象的で分かりづらいです。

また、Open API はその名の通りオープンな仕様なので色々なツールで読み書きやクライアントライブラリの自動生成が可能です。

Open API と相互運用できたら最高だなと思いました。→追記:できますが、Postman Enterprise Ultimate plan が必要です。

みやすさ

ユーザ（開発者）に取ってみれば Postman で API が提供されている方が楽にテストできるので便益性が高いです。
Open API のビューアは貧弱なので辛いです。玄人向けという感じです。

日本語対応

ワークスペース名に日本語を使うといくつかの機能において意味不明なエラーが出て使えなくなることがありました。
今回のテストは Workspace 名に日本語を使っていますがアルファベットだけにしておきましょう。

まとめ

  • Postman の UI はかなり優れているしテストも GUI 上で書けるので便利です。
  • Postman と OpenAPI との棲み分けがまだ整理できていないような感じがしました（理解が浅いだけかもしれません）

追記

Postman の思想がかなり自分の思い描く API のプラットフォームの価値観と一致したので、私が提供している郵便番号検索 API、銀行コード検索 API、駅・路線情報検索 API の仕様を Postman へ追加しました！

Snowflake のようなプラットフォームの API 版という感じがしていてなかなか良さそうです。

image.png

Discussion