Zenn
💡

【VSCode】効率的にAPI開発をするTips

2023/04/14に公開
VS Code
#
curl
Postman
#
restclient
#
jsoncrack
tech

はじめに

API の開発であったり、サードパーティの API を叩く時に楽でいい感じのやり方ってないかな？

この自問にベストな解答が出ないまま、いつも何だかんだ postman か cURL 叩くかを選択していたのですが、今回自分なりにグッドな方法が確立できたので共有です。

postman と cURL を使う中でちょっとめんどくさいなって思ってたことは以下です。

  • postman
    • Editor でない別アプリケーションを起動しないといけない
  • cURL
    • 同じリクエストを繰り返す時にリクエスト内容を保存しておけない
  • 共通
    • リクエストパラメータが多いとき作るのが大変
    • リクエストに連動性を持たせられない
      • 例えば、認証 API を実行 → トークン値を取得し対象の API へリクエストする。という流れで認証 API のレスポンスからトークンをコピーし、対象の API の Authorization ヘッダーにトークンを貼り付けてという作業をしなければならない
    • staging, production でドメインを変更したい時に毎度修正するのがめんどくさい
    • postman、cURL 関係ないが、シンプルに階層が深い Json レスポンスが見ずらい

上記から以下の要望を満たせる方法を考えました。

  • リクエストを Editor(VSCode)内で完結させたい
  • リクエストを保存しておきたい
  • リクエストパラメータを保存しておきたい
  • リクエストに連動性を持たせたい
  • 環境変数を使い分けたい
  • レスポンスが見やすくていい感じの見た目にしたい

いい感じって思ったら是非参考にしてもらえると嬉しいです！

この記事でわかること

この記事を読む上での前提条件

この記事で取り扱わないこと

Rest Client で API リクエストを VSCode から行う

冒頭で挙げた要望の内、以下 5 点は拡張機能 REST Client を使用します。

  • リクエストを Editor(VSCode)内で完結させたい
  • リクエストを保存しておきたい
  • リクエストパラメータを保存しておきたい
  • リクエストに連動性を持たせたい
  • 環境や一部の値を変数などで使い分けたい

基本操作を抑えた上でやり方を確認していきます。

基本的な使い方

使い方は至ってシンプルです。

  • 拡張機能をインストール、.http か .rest 拡張子のファイルを作成
  • ファイル内にリクエスト情報を記載する
  • リクエストを実行する

実際に試してみます。
VSCode を開き、request.http というファイルを作成し、以下の編集を行なってください。

なお、使用する API はオープンに公開されている REQRES というサンプルを使用します。

GET https://reqres.in/api/users?page=2HTTP/1.1
Content-Type: application/json

構成としては {method} {endpoint}{protocol} で記載しその下にヘッダー情報を記載します。
※ Get の場合はメソッドを省略しても OK です
※ HTTP/1.1 は省略可能です

リクエストの送信方法は 3 パターンあります。

１.

リクエスト情報を書くと赤枠で囲ってる箇所のように Send Request というボタンが出現しますのでクリックするとリクエストが送信されます。

2.

ショートカットキー command⌘ + Opt⌥ + r でリクエストが送信されます。

3.

command⌘ + shift⇧ + p でコマンドパレットを開き Send Request を選択するとリクエストが送信されます。

レスポンスは以下のように返ってきます。

基本的な操作方法を理解したところで先ほどの要望を確認してみます。

リクエスト内容の保存

こちらはテキストファイルでリクエスト内容を記載しているので既に要望はクリアしていますね。
加えてリクエスト内容を ###で区切る ことで複数管理することもできます。

GET https://reqres.in/api/users?page=2HTTP/1.1
Content-Type: application/json

###

POST https://reqres.in/api/users HTTP/1.1
Content-Type: application/json

{
    "name": "morpheus",
    "job": "leader"
}

リクエストパラメータを保存

リクエストボディのパラメータを設定する際、都度ファイルの値を修正するでも問題はないと思いますが、値が多い時などはめんどくさいですし、修正間違いもあるでしょう。

使いたい数だけリクエストを作っておくも良いですが、ファイルボリュームが大きくなり読みづらくなりそうですね。

できれば 1 リクエスト分の記述で複数のリクエストボディのパラメータをスイッチしたい。

そんな時、Rest Client ではリクエストボディ部分のファイル読み込み が可能ですのでリクエストボディ部分をファイルとして切り出しておくことで対応できます。

使用例は以下です。

request.body1.json
{
  "name": "hoge",
  "job": "hoge"
}
request.body2.json
{
  "name": "hoge",
  "job": "hoge"
}

POST  https://reqres.in/api/users?page=2HTTP/1.1
Content-Type: application/json

< ./request.body1.json

パラメータごとに json ファイルを用意しておいて < path で読み込みを行うだけです。
リクエストの形式によって XML などで使い分けれます。

それぞれのレスポンスもパラメータの値に沿って可変していることが確認できます。


リクエストに連続性を持たせる

認証 API → トークン取得 → トークンを Bearer ヘッダに設定してリクエスト

上記の流れを確認します。
ここは 変数 部分をうまく使って認証 API のレスポンスの値を変数に格納するようにすれば実現できます。

プロンプト変数を使った例

プロンプト変数 を使えばリクエスト送信時に値の入力が求められ対話的にリクエストを生成できます。

使い方は変数の定義は # @prompt 変数名 の規則で行い、変数の埋め込みは {{変数名}} で行います。

以下、使用例です。

POST  https://reqres.in/api/login
Content-Type: application/json

{
    "email": "eve.holt@reqres.in",
    "password": "cityslicka"
}

###
# @prompt token

GET https://reqres.in/api/users?page=2
Content-Type: application/json
Authorization: Bearer {{token}}

ヘッダー部分の Authorization にプロンプト変数 token 埋め込んでいるのが確認できます。

操作イメージは以下です。

リクエスト変数を使った例

リクエスト変数 を使えば特定のリクエストのレスポンス結果を別のリクエストの変数値として使用することができます。

使い方は以下です。

  • レスポンスから値を取得したいリクエストに # @name エイリアス名 で名前をつける
  • レスポンス値を使用したいリクエスト内で変数として受け取る
    • e.g. @変数名 = {{エイリアス名.response.headers.プロパティ名}}
    • e.g. @変数名 = {{エイリアス名.response.body.$.プロパティ名}}

以下、使用例です。

# @name login
POST  https://reqres.in/api/login
Content-Type: application/json

{
    "email": "eve.holt@reqres.in",
    "password": "cityslicka"
}

###
@token = {{login.response.body.$.token}}
# @name create
POST https://reqres.in/api/users
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "name": "foo",
    "job": "foo"
}
  • トークンを取得したいので認証 API に対して # @login のエイリアスを設定
  • トークンを使いたいところで {{login.response.body.$.token}} で展開し変数 @token に格納
  • 変数を {{token}} で展開

環境変数での使い分け

環境変数 を使用することで環境ごとに異なる変数値を使い分けることができます。

環境変数は VSCode の settings.json に記載します。
command⌘ + shift⇧ + p でコマンドパレットを開き settings json を入力してファイルを開きます。

ファイル内に任意の環境変数を設定します。以下は設定例です。

{
  "rest-client.environmentVariables": {
    "$shared": {
      "version": "v1",
      "prodToken": "foo",
      "nonProdToken": "bar"
    },
    "local": {
      "version": "v2",
      "host": "localhost",
      "token": "{{$shared nonProdToken}}",
      "secretKey": "devSecret"
    },
    "production": {
      "host": "example.com",
      "token": "{{$shared prodToken}}",
      "secretKey": "prodSecret"
    }
  }
}

local と production で環境変数を分ける例で以下のように機能します。

  • host など環境ごとに設定した値が可変
  • 共通の値は $shared の中に定義可能
  • 共通の値を使う場合は {{$shared プロパティ名}} で指定
  • production 選択時に version を指定した場合は $shared の version が参照される

環境を切り替えたい時は command⌘ + shift⇧ + p でコマンドパレットを開き Switch Environment を選択します。

すると settings.json に定義した環境名が表示されるので任意の環境を選択

環境を切り替えると右下に現在の環境が行事されるようになります。

以下、環境変数を使ったリクエスト例です。

GET https://{{host}}/{{version}}/users
content-type: application/json

使い方は通常の変数の展開と同じですね。

その他 Tips

やりたかったことは全部叶ったのですが、プラスでもう少しだけ機能紹介を書いておきます。

ファイル変数

プロント変数、リクエスト変数は先ほど扱いましたが、一番基本的なファイル変数について触れなかったので解説します。

ファイル変数 は名前の通り、ファイル内で有効な変数が作れます。
使い方は @変数名 で定義し {{変数名}} で展開します。

使う上で注意点がありますので以下に記載します

  • 1 行で書く必要があるので改行はできない
  • 改行を表現する場合は \ でエスケープする必要あり
  • 変数名にスペースは使えない

また、ファイル参照なので全リクエストに共通で変数を使用できます。
例えば以下のような複数リクエストに対して変数を使い回すことが可能です。

@hostname = reqres.in
@contentType = application/json

GET https://{{hostname}}/api/users?page=1
Content-Type: {{contentType}}

###

GET https://{{hostname}}/api/users?page=2
Content-Type: {{contentType}}

システム変数

システム変数 はあらかじめ用意されている変数です。

ドキュメントに変数名ごとに解説があるのでぜひ参照してみてください。

また、自分でシステム変数を設定することも可能です。

.env に記載した値を使用する方法は便利そうだったので試してみました。
使い方はリクエストファイルと同じ階層に .env を作成し {{$dotenv 変数名}} 呼び出すだけです。

ENV_PATH=api/users?page=2

GET https://reqres.in/{{$dotenv ENV_PATH}}
Content-Type: application/json

cRUL に変換

全員が同じ環境で作業できる訳ではないですし、俺は VSCode など使わないしターミナル実行派だから cURL でのリクエスト例をくれ。

なんてことを言われてしまった時の対処として、ファイル内に記載したリクエストを cURL に変換する機能があります。

command⌘ + shift⇧ + p でコマンドパレットを開き Copy Request As cURL を選択するとスニペットに cUR 版のリクエスト情報がコピーされますので、command⌘ + v で貼り付ければ OK です。

以下変換したコマンドです。

$ curl --request GET \
  --url 'exports.exec%20=%20async%20(connection,%20id)%20=%3E%20%7B' \
  --header 'user-agent: vscode-restclient'

API レスポンスの見た目をいい感じにする

冒頭の以下の要望に対してのアプローチです。

  • レスポンスが見やすくていい感じの見た目にしたい

いい感じのサービスはないかなと思い探してたのですが、JSON CRACK がいいなと思いました。

こんな見た目です。

ただ、このようなサービスを使う上で気をつけないといけないのって悪意がなくとも公開される可能性があるため、業務情報を含むようなデータは絶対にアップロードできないってとこですよね。

大体ここがネックで基本的にいいなってサービスがあっても使うの躊躇するのですが、JSON CRACK は太っばらなことにパブリックでリポジトリ公開してくれてるようです。

https://github.com/AykutSarac/jsoncrack.com

なのでこちらをローカルサーバで起動して使用するようにすれば比較的安全に使えるなと思ったので Rest Client と組み合わせて使うことでいい感じの API 開発ライフが送れるのではと思い紹介させていただきました。

さいごに

さいごまで読んでいただきありがとうございます。

エディタは好みがあると思うので同じ VSCode をメインで使っていていい感じの使い方と感じる方がいらっしゃいましたら是非ご参考にしてください b

間違いの指摘やリクエストなどありましたら加筆していきたので是非、ご意見をいただけたらと思います。

それではまた次の記事でお会いしましょう。

GitHubで編集を提案

Discussion