「APIをたたく」「カールコマンド(お菓子の"カール"？)を打つ」 などがさっぱりわからない。だから、恥も外聞も無しにAIに１から聞いてみた。
cURLコマンドでAPIを叩くということ
cURL("カール"と読む)でAPIをたたく作業とは、
「プログラムから実行されるAPIを、自分のPCから手動で実行して結果を確認する作業」
です。
API開発や検証では非常によく使います。
まずAPIとは？
APIを簡単に説明すると
- 人間がURLにリクエストを送る
- サーバーが処理する
- 何かしらの結果を返す
という仕組みです。
例えば
https://api.example.com/users
にアクセスすると
[
{
"id": 1,
"name": "Taro"
}
]
みたいな結果が返ってくるようなものです。
つぎにcURLとは？
cURL ( "カール" と読む) は
HTTP通信をコマンドラインから実行するツール
です。
ブラウザの代わりにコマンドでAPIを呼び出せます。
一番簡単な例
APIへGETリクエスト
curl https://api.example.com/users
実行
$ curl https://api.example.com/users
結果
[
{
"id": 1,
"name": "Taro"
}
]
主なメソッド
APIでは主に以下を使います。
| メソッド | 用途 |
|---|---|
| GET | 取得 |
| POST | 登録 |
| PUT | 更新 |
| DELETE | 削除 |
GET
データ取得
curl https://api.example.com/users/1
POST
データ登録
curl -X POST https://api.example.com/users
JSONデータを送る
ユーザー登録APIの例
送信内容
{
"name": "Natsumi",
"age": 22
}
cURL
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"Natsumi","age":22}'
オプションの意味
-X
HTTPメソッド指定
-X POST
-H
ヘッダー指定
-H "Content-Type: application/json"
意味
JSON形式で送ります
-d
送信データ
-d '{"name":"Natsumi"}'
意味
リクエストボディ ( "リクエストの中身" ということ)
認証が必要なAPI
業務APIではほぼ必須です。
例
curl https://api.example.com/users \
-H "Authorization: Bearer xxxxx"
Bearer Tokenとは？
簡単に説明すると、 「ログイン済み証明書」 のようなもの
あなたは実行してよいですよ
という認証情報のことを言う。
実務でよく見るGraph API
例えばOneNoteの中の情報を一覧取得しようとすると、
curl \
-H "Authorization: Bearer ACCESS_TOKEN" \
https://graph.microsoft.com/v1.0/me/onenote/notebooks
返却
{
"value": [
{
"displayName": "My Notebook"
}
]
}
APIをたたくときの確認ポイント
業務で「cURLコマンドでAPIを叩く」タスクに出くわしたときは、以下の順でタスクを消化していきましょう。
1. URL
指定のURLが本当に正しいかどうか確認する
https://graph.microsoft.com/v1.0/...
2. メソッド
GETなのかPOSTなのか、メソッドの用途を確認する
-X GET
3. Headerの指定
認証情報があるか
-H "Authorization: Bearer xxx"
4. Body
POST時のJSONが正しいか
{
"name": "test"
}
よくあるエラー
401 Unauthorized
意味
認証失敗
確認
- Token期限切れ
- Token未設定
- Permission不足
403 Forbidden
意味
権限不足
確認
- API Permission
- SharePoint権限
- OneNote権限
404 Not Found
意味
URL誤り
確認
- Endpoint
- Resource ID
実務での流れ
例えばGraph API検証なら
① Access Token取得
↓
② curl実行
↓
③ JSON確認
↓
④ 正常ならPythonに実装
まずcURLで成功させてからコード化します。
最初に覚えるテンプレート
これだけ覚えておけば十分です。
curl -X GET \
"https://api.example.com" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json"
見るポイントは4つだけです。
URL
Method
Header
Body
API仕様書を見ながら、この4つを埋めればAPIをたたけるようになります。