InsomniaでAPI実行環境を素早く作る
この記事は🎄GMOペパボエンジニア Advent Calendar 202225日目の記事です。
OAuth2認可フローを採用したAPIを検証するとき、認可コードを取得してから更にアクセストークンをもらって〜というフローがちょい面倒と感じていたのだけれども、Insomniaでシュッとできるようになっていることに気がついたのでメモ書き。
折角なので今回は筆者の所属している社のサービスであるカラーミーショップで試す。
前提
- Insomniaが起動すること
- 以下のどちらかを満たされていること
- カラーミーショップのショップアカウントを持っている
- カラーミーショップデベロッパーサイトからテストショップを利用できる状態になっている
カラーミーショップのAPIドキュメント
カラーミーショップでは外部連携を行うユーザーのためにAPIを公開している。 ドキュメントはこちら。
カラーミーショップAPIのOpenAPI specificationは以下のURLより取得できる
手順
- (カラーミーショップ)プライベートアプリの追加
- (Insomnia)OpenAPI specificationのインポート
- (Insomnia)でアクセストークンの取得
- (Insomnia)でAPIリクエスト
プライベートアプリの追加
ホーム - カラーミーショップ デベロッパー でデベロッパーアカウントを発行したあと、同ページより追加できる。アプリを追加することで、Client ID, Client Secretが発行される。
OpenAPI specificationのインポート
InsomniaはOpenAPI specificationのファイルを入力としてAPIのリクエスト設定(Request collection)をインポートできる。
IMPORT FROM URL を選択してOpenAPI specificationのURLを入力する。
Request Collectionとしてインポートする。
すると、カテゴリごとにフォルダに分かれた形でAPIがインポートされる。
アクセストークンの取得
それぞれのAPIの OAuth 2 のタブを開くと、アクセストークンを取得するための設定もある程度インポートされていることがわかる。
oauth2ClientId や oauth2ClientSecret などは変数になっていて、Manage Environmentsのメニューから設定を変更することができる。ここで、デベロッパーページで追加したアプリのClient IDとClient Secretを設定しとくとRequest collectionの共通設定となって便利。
また、OAuth 2のタブではAdvanced Optionsの項目からScopeの指定ができる。
カラーミーショップAPIの場合、一部のAPIではスコープを適切に設定する必要がある。複数指定したい時はスペース区切りで入力すると良い。Scopeには以下の項目が利用でき、その詳細はデベロッパーページを参照すること。
| スコープ | 機能 |
|---|---|
| read_products | 商品データの参照 |
| write_products | 在庫データの更新 |
| read_sales | 受注・顧客データの参照 |
| write_sales | 受注データの更新 |
| read_shop_coupons | ショップクーポンの参照 |
APIリクエスト
Client ID, Client Secret, Redirect URLを設定した状態でSendを押すと認可画面に進む。
既に登録済のカラーミーショップのアカウント情報を入力してログインしたあと、認可画面へ。
スコープが未入力だと、デフォルトではショップ情報しか認可されないので注意すること。
「アプリを連携」を押すことで認可コードを付与した状態でリダイレクトされる、認可コードをInsomniaが自動で取得し、OAuth 2の設定の ACCESS TOKEN URL のURLを利用してアクセストークンのリクエストまで行ってくれる。これが便利。
レスポンスが返ってくれば💯
OAuth 2の認可フローを通るAPIで適切にAPI定義が書かれていれば別の公開APIでも同じように設定できると思う。使ってみると、設定のインポート結果が不十分な箇所がまだあるので、そこは定義を直していきたい。
Discussion