はじめに

curlコマンドを使ってapiを叩いたりするのですが、curlコマンドってただapiを叩くためのコマンドなの？みたいなレベル感でした。
業務で使ったコマンドを簡略化すると下記になるのですが、オプションの意味とかよくわからなかったので勉強がてらまとめてメモしました。

curl -k -v -A "アプリのユーザーエージェント" "uri" | jq

参考にしたサイトは下記のマニュアル
https://curl.haxx.se/docs/manpage.html

curlコマンドとは

curlコマンドとはサーバから、もしくはサーバへデータ転送を行うコマンドです。
curlコマンド自体はapiを叩くためだけに存在しているわけではないです。

httpリクエストができるコマンドなのかなーって思ってたのですが、実際には
HTTPやHTTPSといったプロトコルに対応しているため、GETでAPIを叩いたりすることができるというだけで、
curlコマンド自体はFTP,SFTP,LDAP,TELNETなど多くのプロトコルに対応しています。

下記の書式でコマンドが実行できます。

curl [options] [URL]

jqコマンド

curlとは関係ないが、curlでapiを叩く時に一緒に使うと便利です。
jqコマンドは入力を受け取り、出力を生成するフィルタの役割を果たします。

特定のデータを抽出したり整形したりできるのですが、今回は整形して見やすくするためだけに使用します。

インストールはhomebrewでできます。

brew install jq

実際に何が違うかというと
jqコマンドなし

echo '{"message": null, "results": [{"address1": "高知県", "address2": "南国市"}], "status": 200}';

{"message": null, "results": [{"address1": "高知県", "address2": "南国市"}], "status": 200}

jqコマンドあり

echo '{"message": null, "results": [{"address1": "高知県", "address2": "南国市"}], "status": 200}' | jq;

{
  "message": null,
  "results": [
    {
      "address1": "高知県",
      "address2": "南国市"
    }
  ],
  "status": 200
}

便利なオプション

HTTPヘッダを出力させる

「-i」 HTTP ヘッダを出力に含めます。
「-I」 HTTP ヘッダのみを取得します。

curl -I "http://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060"

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-Cloud-Trace-Context: f49b7a1f7109801bca6e70de691430a3
Date: Sat, 17 Dec 2016 05:37:51 GMT
Server: Google Frontend
Content-Length: 290

ちなみにjqコマンドとの併用はできない

curl -I "http://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060" | jq 

parse error: Invalid numeric literal at line 1, column 9

jqコマンドで扱える形式はjsonだからです。

リクエストのヘッダとレスポンスのヘッダを表示する

「-v」を指定することで、リクエストとレスポンスのヘッダを表示できます。

ユーザーエージェントを指定

「-A」 "ユーザーエージェント"　を指定することで、特定のユーザーエージェントでのリクエストであると認識されます。
例えばアプリからAPIを叩く挙動を確認したい時に使用できます。

curl -A "ユーザーエージェント" "http://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060"

SSL/TLSのエラーをスキップする

「-k」を指定するとSSL/TLSのエラーをスキップできます。（安全でないSSL/TLS接続を行う）
オレオレ証明書なんかを使用している時に「-k」オプションをつけます。

オレオレ証明書とは

正式には自己署名証明書と呼ばれています。
公開鍵に署名をする際に、その公開鍵に対応した秘密鍵で署名を行った公開鍵証明書のことです。
通常はサーバ証明書は「信頼できる認証機関」が署名を行うのですが、それを自分で署名を行っているため、オレオレ証明書と呼ばれています。

POST

APIに対してPOSTでリクエストを行う場合には-X POSTを指定する。
パラメータをつけてPOSTでリクエストを行う場合には、-dでパラメータを指定する。

curl -X POST [url] -d "name=hoge"
curl -X POST [url] -d "name=hoge&age=20"

結果に応じてコマンドを実行

Software Designでcurlコマンドの使い方が紹介されていたのですが、特定の結果が返ってきた場合に何かコマンドを実行させる(再起動など)という使い方もあるそうです。

$ curl --silent "http://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060"
{
    "message": null,
    "results": [
        {
            "address1": "高知県",
            "address2": "南国市",
            "address3": "蛍が丘",
            "kana1": "ｺｳﾁｹﾝ",
            "kana2": "ﾅﾝｺｸｼ",
            "kana3": "ﾎﾀﾙｶﾞｵｶ",
            "prefcode": "39",
            "zipcode": "7830060"
        }
    ],
    "status": 200
}
$ curl --silent "http://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060" | grep "北海道" >/dev/null 2>&1 && echo "hoge"
$ curl --silent "http://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060" | grep "高知県" >/dev/null 2>&1 && echo "hoge"
hoge

その他

下位10％のダメなエンジニアにだけ解けないパズル

前に話題になったらしい問題です。こちらから試せます。
最低限のcurlの知識があればできるのでやってみてください。
正解が欲しい方は下位10％の〜で検索してもらえればいろいろと出てくると思います。

Postman

Chromeの拡張機能として提供されています。
Postman

json形式で記載されている仕様書があり、それをコマンドにするよりも、そのままコピペしたかったのでこちらを使用していました。
登録もできるので、よく使うものはこちらに登録するのも良いと思います。

ログインが必要なサイトへのcurl

デベロッパーツールのネットワークから、一番上のリクエストを選択して右クリックをする。
copy as curlを選択するとcookie情報等もオプションで指定されたcurlコマンドを生成してくれる。

ヘッドレスブラウザ

web上のリソースへのアクセスをするのに、GUIを持たずにコマンドやNode.jsから操作できるヘッドレスブラウザを使用することもできます。
ただ、curlに比べて起動にかかる時間とメモリなどのリソースも大きくなりがちだそうです。
ヘッドレス Chrome ことはじめ

今回はAPIを想定していますが、仮にcurlでhtmlを取得しようと思った場合、jsレンダリング前のhtmlしか取得ができないため、ヘッドレスブラウザを使う必要が出てくるかもしれません。

スニペットツール

apiを作るときに自分で開発期間中に何度かapiを叩くことがあります。
その都度書くのはめんどくさいので、Clipyというスニペットツールに登録をしていつでもすぐにapiを叩けるようにしています。
【参考】クリップボード拡張Macアプリ「Clipy」を公開しました

まとめ

オプション数はかなり多いので、使うときは色々と調べながらやると良いですね。
これに限った話ではありません、同じコマンドをなんども書かないようなツールの選定や工夫も必要だなと書いてて改めて思いました。

curlコマンドでapiを叩く