.http (ドットエイチティティーピー) ファイルを作ると、HTTPリクエストを手軽に送信することができます。

例えばAPIサーバを作ったなど時に、検証でリクエストを送ると思います。Webフレームワークに含まれるユニットテストは別として、任意にリクエストを発行して検証する場合は

ウェブブラウザ
curlコマンド
Postmanアプリ
Python+Requests や、JS+Axios のようなスクリプト言語

などがよく使う方法だと思います。

ウェブブラウザを使ってのテストは、ヘッダーやリクエストボディを扱うのが難しかったり、Postman や Python などは複雑な処理が行える分、実際にリクエストを発行するまで少し手間がかかり、試したい内容に比べて大仰だったりします。

.http でのリクエストは、ファイル記述が明快で、JetBrains のエディター (PyCharm , WebStorm) にはデフォルトでプラグインやテンプレートが含まれているため、素早く作って検証するのに最適です。Visual Studio Code はプラグインがありますので、それを入れると快適に使えます。

もし、APIの認証で、リクエスト内容から hmac で署名を求めてリクエストに含めるとか、jwt を扱うとか、そういった複雑な処理を含むのであれば、.http では難しいので、postman やスクリプト言語を使った方が良いと思いますが、セッションクッキーやベアラトークンでの認証や、Basic/Digest 認証程度であれば、.http がちょうどよく役に立ちます。

.http スクリプトの文法

POST http://localhost/api/item
Content-Type: application/json

{"id": 99, "content": "new-element"}

###
POST http://localhost/api/item
Content-Type: application/x-www-form-urlencoded

id=99&content=new-element

###
GET http://localhost/api/item?id=99
Accept: application/json

1行目にメソッドとリクエストURL、2行目以降はリクエストヘッダー、空行を1つはさんでリクエストボディとなります。基本的に、これだけです。 ### を区切りとして、複数のリクエストを1つの .http ファイル中に書けます。

変数展開

GET {{host}}/get?show_env={{show_env}}
Accept: application/json

{{ 〜 }} で変数を指定できます。変数は環境ファイルから読み込まれます。ステージングサーバと本番サーバで値を分けたい時に使います。

処理系・実装

Google 検索すると、こちらの、bayane さんが rust で書かれているコードが出てきて、他にそれらしいのは見当たりませんので、この方が考えられたものなのでしょうか。

仕様自体は昔からあって、rust 実装は bayane さんが作られたような気がしなくもないですが、非常に検索しにくい名前のため詳細はわかりませんでした。

実際に扱うとしたら、エディタに含まれるプラグインを使う場合が多く、この dot-http コマンドをCUI から実行することはまずありません。

JetBrains のエディタから使う

Scratch から作る

デフォルトの状態で、Scratch から .http が作れるようになっています。

Command + Shift + N の、New Scratch File から、 http とタイプして HTTP Request を選択します。

空ファイルが作られますが、上に専用メニューが表示されています。このメニューから簡単にテンプレートを呼び出せます。

Add request から GET Request を選ぶと…

GETリクエストのテンプレートが呼び出されます。あとは内容を書き換えて、 ▶ をクリックすると、リクエストが発行され、結果が出力欄に出てきます。

JSON を POST するリクエストなども、同様にかなり手軽に素早く作ることができます。

変数ファイルを作って環境ごとに異なる変数を埋め込む

ディレクトリの中に、http-client.env.json という名前でファイルを作ります。

http-client.env.json

{
  "local": {
    "host": "http://127.0.0.1:8000",
    "sessionId": "xxxxxxxxx"
  },
  "staging": {
    "host": "https://staging.example.com",
    "sessionId": "xxxxxxxxx"
  },
  "production": {
    "host": "https://production.example.com",
    "sessionId": "xxxxxxxxx"
  }
}

すると、他の .http ファイルから、変数が使えるようになります。

request.http

GET {{host}}/api/item?id=99
Accept: application/json
Cookie: sessionid={{sessionId}}

###

エディタで ▶ をクリックすると、環境を選んでリクエストを発行できます。

PyCharm で試した所、プロジェクト内にあるすべての http-client.env.json を探して、使えるようになってました。

その他のリクエスト例

上部メニューの「Examples」に、いくつかサンプルが入ってます。記述がシンプルなので、見るだけですぐ理解できる内容となっています。

リダイレクトを追わない

### GET request with disabled redirects
# @no-redirect
GET http://httpbin.org/status/301

デフォルトでは、リダイレクトレスポンスはそのまま GET で追従します。
@no-redirect を書くと、リダイレクトレスポンスがそのまま見れます。

レスポンスのテストをする

### Successful test: check response status is 200
GET https://httpbin.org/status/200

> {%
client.test("Request executed successfully", function() {
  client.assert(response.status === 200, "Response status is not 200");
});
%}

レスポンスオブジェクトを JS で処理・検証できます。

Visual Studio Code で使う

REST Client という機能拡張で同様のことが行なえます。

というか、調べていて思ったのですが、 .http という呼び名より、この REST Client の方が有名だったみたいで、 REST Client の使い方の記事が多く出てきました。結果、私のこの記事はそれらの内容の丸コピーみたいになってしまいました。

とはいえ、Advent Calender の担当分として書いちゃったのでそのまま公開します。