3行まとめ
- この記事は Postman Advent Calendar 2023 のシリーズ2、17日目の記事です。
- Postmanにアカウント登録して既存のREST API仕様を登録し、Flow、Test、Visualizationを使ってみました。
- 昔は無料でできることが少なかった気がしましたが、今は無料で色々できます。
背景
業務でWebアプリケーションを作成しているときに、「こんなWeb APIがあったら楽なのに」と思うことがあり、なければ作ってしまえば良いと思い、個人的に無料で簡単に利用できるREST APIによるデータ公開を行っています。
例えば住所の自動補完に使う郵便番号API、インボイス登録番号に関連した法人番号検索APIなどです。
今回は法人番号検索APIを扱います。
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を公開しています。
PostmanにAPIを登録して設定
ユーザ登録をした上で、APIを登録する準備を進めていく手順を紹介します。
初期化
APIを登録するためにはワークスペースを作る必要があります。
API仕様はパブリックなのでpublicを選びます。
publicにする場合は、自分のプロフィールに公開用の情報を追加する必要があるのでダイアログに出たとおりに設定してOKを押します。
ちなみにこちらが私のプロフィールページになります。
https://www.postman.com/matsubokkuri
OpenAPIのファイルをインポートできる機能があったので早速importしてみます。
OpenAPIファイルをインポート
どうやってインポートをするか聞かれましたが、デフォルトで進んでみます。
追記: 上の Postman Collection はPostmanでの標準となるAPI仕様のフォーマットです。下の、OpenAPI 3.0 witha Postman Collection はOpenAPI 3.0との互換性を保った上でのAPI表現と、Postman独自のCollectionの両方に追加されます。今回は、Postman専用に不可逆なファイルコンバートとして割り切ります。
インポートが完了すると左側にメニューに階層化されて表示されました。
しかしながら、階層が多いように感じたので適切なコレクションを作成して、エンドポイントを適切なコレクションに入れ直しました。ドラッグ・アンド・ドロップで移動できるので楽です。
エンドポイントの名前が見づらかったので少し修正しました。これでAPIを使う開発者にとってもかなり見やすくなったと思います。
機能を使ってみる
早速テストで法人番号の一覧を表示するAPIを呼び出してみます。下のペインに結果が整形されて表示されました。
Visualizationのタブを選ぶと上のJSONの結果がテーブルに勝手に整形されて表示されました。見やすいです。
グラフ化できるような値の場合はグラフとして表示できるようです。
仮にline chartで描画してみました。メトリックや集計はできなさそうです。自動で選ばれたメトリックがXとYに設定されました。自動で作成できるのは楽です。
一覧の取得はパラメータを一切必要としませんでしたが、今度は1つの法人の情報を取得してみます。
変数となる部分は、collectionのスコープで定義されているようです。
左のメニューの一番上のコレクションを選択したら変数の一覧とデフォルト値が表示されました。
有効な値に変更していきつつ、サーバのURLといった環境依存の変数はEnvironmentに移します。
完成した設定がこちらです。コレクションスコープ。
こちらは環境スコープです。
注意点
- 右上に「Save」ボタンがあるので毎回押し忘れないように気をつけましょう。
- Current Valueのカラムにある値が使われるのでこちらも合わせて正しい値を設定しておきましょう。
ということで、法人の情報を1件取得してみます。結果が下のペインに表示されました。
同様に、他のエンドポイントに対しても適切にパラメータや変数を設定していき、呼び出しができることを確認します。
APIの自動テスト
APIが正常に動作しているか、適切なスキーマで返却されているかをテストできる機能があります。
テストの内容は、コレクション単位、エンドポイント単位で設定できます。
以下の例は、コレクション単位で設定できるテストの部分に書いてあります。
単純に200番が返ってくるかどうかをテストするような汎用的な内容です。
上記を実行すると以下のようになります。各エンドポイントの呼び出しに対して評価されます。
今度は、個別のエンドポイントでテストを書いてみます。
簡易的に、配列で値が返ってくるかを書いてみます。保存して、下のリフレッシュボタンを押すとテストを実行できます。
テスト内容はGPTに問い合わせることで半自動で作成でるので楽です。
しかしながら、デバッグ方法がちょっとわかりませんでした。consoleに出力してもその内容がどこに出るの発見できませんでした。
今度は、コレクションの方に戻って定期的に自動テストを実行するように設定しておきます。これによって、APIが仕様通りに動いているかをPostmanを見るだけでひと目でわかるようになります。
このあたりはOpenAPIのスキーマを自動的に読み込んで、自動的にテストを書いてほしいものです。
monitorの設定
外部監視が設定できます。
定期的にテストを実行して死活監視してくれるようです。
Flowの作成
Postman上でAPIや計算処理をしてワークフローを構築できるサービスです。
法事番号検索APIでは、各都道府県ごとの法人数を返却するエンドポイントがあるのでシンプルですがグラフ化してみます。
ものの2分でグラフが構築できました。簡易的なダッシュボードとしても使えそうです。
プロフィールの整備
最後にプロフィールを入力しておきます。
デフォルトのアイコンが何を意味しているのかよくわからないので写真も設定しておきました。
こんな感じで表示されました。かっこ良いです！
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版という感じがしていてなかなか良さそうです。
