curlでAPIをたたいてみる入門
APIについて調べていると、curlで確認してみる という表現をよく見かけます。
でも、IT初心者のうちは
- curlって何？
- APIをたたくってどういう意味？
- どんなふうに使えばいいの？
と感じることも多いと思います。
この記事では、IT初心者向けに、次の内容をできるだけやさしく整理します。
- curlとは何か
- APIをたたくとはどういうことか
- GETとPOSTをcurlで試す基本
- 結果をどう見ればよいか
curlとは？
curlは、コマンドラインからHTTPリクエストを送るためのツール です。
ブラウザでWebページを見る代わりに、ターミナルやコマンドプロンプトから直接リクエストを送れるイメージです。
たとえば、ブラウザでページを開くと、裏側ではサーバーにリクエストが送られています。
curlを使うと、そのやり取りを自分でシンプルに試せます。
「APIをたたく」とは？
「APIをたたく」とは、APIに対して実際にリクエストを送って、レスポンスを確認すること を指すことが多いです。
たとえば、次のような場面で使います。
- このURLでデータが取れるか確認する
- POSTで登録できるか試す
- エラー内容を確認する
少しくだけた表現ですが、現場でもよく使われます。
なぜcurlを使うのか
curlを使うと、次のようなことがしやすくなります。
- APIが正しく動いているか確認できる
- フロント画面を使わずにAPIだけ試せる
- エラーの切り分けがしやすい
- リクエスト内容を明示的に指定できる
特に、画面ではうまくいかないけれど、API自体はどうなのか確認したい ときに便利です。
まずはGETを試してみる
最初に、データ取得の基本であるGETを見てみます。
たとえば、次のようなコマンドです。
curl https://example.com/api/users
これは、
-
https://example.com/api/usersに対して - GETリクエストを送り
- 結果を表示する
という意味です。
curlでは、何も指定しないとGETになることが多いので、まずはこの形から覚えると分かりやすいです。
返ってくるレスポンスのイメージ
レスポンスとして、たとえば次のようなJSONが返ってくることがあります。
[
{
"id": 1,
"name": "Taro"
},
{
"id": 2,
"name": "Hanako"
}
]
これは「ユーザー一覧が返ってきた」という意味です。
初心者のうちは、まず
- ちゃんと何か返ってきた
- JSON形式でデータが見える
という理解で大丈夫です。
POSTを試してみる
次に、データ送信の基本であるPOSTです。
たとえば、ユーザー登録をしたい場合は次のように書きます。
curl -X POST https://example.com/api/users \
-H "Content-Type: application/json" \
-d '{"name":"Taro","email":"taro@example.com"}'
少し長く見えますが、分けて見ると理解しやすいです。
-
-X POST
→ POSTメソッドで送る -
-H "Content-Type: application/json"
→ JSON形式のデータを送ると伝える -
-d '...'
→ 実際に送るデータ本体
つまりこのコマンドは、users APIに対して、JSON形式のユーザー情報を送っている ということです。
よく使うオプションをざっくり理解する
curlはオプションが多いですが、最初は次の3つを押さえれば十分です。
-X
HTTPメソッドを指定します。
例：
curl -X POST https://example.com/api/users
POST以外にも、PUT、DELETEなどを指定できます。
-H
ヘッダーを付けます。
例：
-H "Content-Type: application/json"
APIでJSONを送るときによく使います。
-d
送信データを指定します。
例：
-d '{"name":"Taro"}'
POSTやPUTなどで、本文を送るときによく使います。
ステータスコードも確認してみる
APIの確認では、レスポンス本文だけでなく、HTTPステータスコード も重要です。
たとえば次のようにすると、ステータスコードを確認しやすくなります。
curl -i https://example.com/api/users
-i を付けると、レスポンスヘッダーも一緒に表示されます。
そこに例えば
HTTP/1.1 200 OK
のように出ていれば、成功です。
よくある例はこんな感じです。
-
200: 成功 -
404: URLが見つからない -
500: サーバー側エラー
APIをたたいた結果が想定通りかどうかを見るとき、ステータスコードはとても大切です。
認証が必要なAPIはどうする？
実際のAPIでは、認証情報が必要なことも多いです。
その場合は、ヘッダーにトークンを付けて送ることがあります。
たとえば次のような形です。
curl https://example.com/api/users \
-H "Authorization: Bearer xxxxxx"
これは、認証トークンを付けてAPIを呼び出している例です。
初心者のうちは、「APIによってはログイン情報のようなものが必要」 くらいの理解で問題ありません。
curlを使うときにハマりやすいポイント
初心者がつまずきやすいポイントもあります。
URLが間違っている
APIのパスが少し違うだけでも、404になります。
GETとPOSTを間違える
取得したいのにPOSTしていた、登録したいのにGETしていた、ということがあります。
JSONの書き方が間違っている
ダブルクォーテーションの抜けやカンマの位置ミスでエラーになることがあります。
ヘッダー不足
Content-Type や認証ヘッダーが必要なのに付いていないと、うまく動かないことがあります。
まずは何を試せばいい？
初心者なら、まずは次の順番がおすすめです。
- GETでデータ取得を試す
-
-iを付けてステータスコードを見る - POSTで簡単なJSON送信を試す
- ヘッダー付きのリクエストを試す
この順番で触ると、少しずつ理解しやすいです。
まとめ
curlは、コマンドラインからAPIにリクエストを送るための便利なツール です。
APIをたたくとは、実際にリクエストを送って、レスポンスやステータスコードを確認すること だと考えると分かりやすいです。
初心者のうちは、まず次の3つを押さえるのがおすすめです。
- GETでデータ取得ができる
- POSTでデータ送信ができる
- ステータスコードを見ると結果を判断しやすい
curlが使えるようになると、APIの理解がかなり深まります。
画面の裏側で何が起きているのかを、自分の手で確認しやすくなるからです。
最初は難しく見えても、まずは1本のGETリクエストを試すところから始めると入りやすいと思います。