API
1. APIとは何か?
APIは「アプリケーションの窓口」のようなもの。
例えば、レストランのウェイターが注文をキッチンに伝え、料理を運んできてくれるように、APIは「リクエスト(要求)」を送り「レスポンス(結果)」を受け取る役割をします。
2. リクエストとレスポンス
APIを使う時、次の2つが基本です。
- リクエスト:データや処理を要求すること
- レスポンス:その結果として返ってくるデータ
例えば、天気情報APIに「今日の東京の天気は?」とリクエストすると、「晴れ、気温25度」とレスポンスが返ってきます。
リクエストとレスポンスには主に以下の2つの部分が含まれます:
ヘッダー(Header)
ヘッダーはリクエストやレスポンスの「メタ情報」が含まれる部分です。例えば、以下のような情報が含まれます:
リクエストヘッダー
- 認証情報(例:APIキー)
- リクエストの形式(例:Content-Type: application/json)
- サーバーが受け入れるデータの形式(例:Accept: application/json)
例:
GET /weather/tokyo HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
レスポンスヘッダー
- サーバーの情報(例:Server: nginx)
- レスポンスの形式(例:Content-Type: application/json)
- リクエストの結果に関する情報(例:Content-Length: 123)
例:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 123
ボディー(Body)
ボディーは、リクエストまたはレスポンスの「中身」を指します。データそのものが含まれます。
リクエストボディー
- POSTやPUTリクエストで送信するデータが含まれます。
例:
{
"city": "Tokyo",
"date": "2024-12-19"
}
レスポンスボディー
- サーバーから返されるデータが含まれます。
例:
{
"city": "Tokyo",
"weather": "Sunny",
"temperature": 25
}
ヘッダーとボディーの役割の違い
- ヘッダーは通信を管理するための情報を含む。
- ボディーは、実際にやり取りするデータを含む。
3. APIのルール(プロトコル)
APIにはルールがあり、その中でもよく使われるものがHTTPです。HTTPでは「メソッド」というものを使います。
代表的なものは以下の4つです:
- GET:データを取り出す時(例:天気情報を取得する)
- POST:新しいデータを作る時(例:新しいコメントを投稿する)
- PUT:データを更新する時(例:プロフィール情報を更新する)
- DELETE:データを削除する時(例:コメントを削除する)
4. エンドポイント(Endpoint)
APIを使う時は「エンドポイント」と呼ばれるURLを使います。
例えば:
https://api.example.com/weather/tokyo
このエンドポイントに「GETリクエスト」を送ると、東京の天気情報が返ってきます。
以下のように記事に追記すると適切です。
5. データの形式
APIでやり取りするデータは、ほとんどの場合JSONという形式で書かれています。
JSONの例:
{
"city": "Tokyo",
"weather": "Sunny",
"temperature": 25
}
JSONは「名前(キー)」と「値」がペアになったシンプルなデータ形式です。
JSONデータの扱い方
APIから返されるJSONデータは、文字列形式で送られてきます。そのままでは扱いにくいので、JavaScriptオブジェクトに変換する必要があります。
以下のメソッドを使います:
- JSON.parse(): JSON文字列を取得し、JavaScriptオブジェクトに変換します。
- JSON.stringify(): JavaScriptオブジェクトを取得し、JSON文字列に変換します。
- response.json(): JSON形式の文字列を自動的にJavaScriptオブジェクトに変換してくれます。
なぜ response.json() が必要なのか?
APIから返されるデータは通常、文字列として送られてきます。このままではデータにアクセスするのが難しいため、JavaScriptオブジェクトに変換する必要があります。
response.json() を使う例:
fetch("https://api.example.com/weather/tokyo")
.then(response => response.json()) // JSON形式をオブジェクトに変換
.then(data => {
console.log(data.city); // "Tokyo"
console.log(data.temperature); // 25
});
使わない場合(エラーになる例):
fetch("https://api.example.com/weather/tokyo")
.then(response => {
console.log(response.city); // undefined
});
この場合、response は「JSON文字列のまま」なので、プロパティにアクセスできません。
6. APIキーと認証
APIを使う時には「APIキー」という鍵が必要な場合があります。
これは、APIを安全に使うための認証情報です。
7. エラーハンドリング(エラー処理)
APIを使うとエラーが起きることもあります。
その時は「ステータスコード」で何が問題なのかがわかります。
ステータスコード | 意味 |
---|---|
200 | 成功(問題なく動いた) |
400 | リクエストが間違っている |
401 | 認証が必要 |
404 | データが見つからない |
500 | サーバーの問題 |
8. APIドキュメントを読む
APIには必ず「ドキュメント」があります。
- 何をリクエストすれば良いのか
- どんなデータが返ってくるのか
が書いてあるので、よく読んで理解しましょう。
9. 実際にAPIを使うシンプルなコード
例えば、天気情報APIにリクエストを送るJavaScriptコード例です。
// APIのエンドポイント
const url = "https://api.example.com/weather/tokyo";
// APIリクエストを送る
fetch(url)
.then(response => {
// HTTPステータスコードの確認
if (!response.ok) {
throw new Error(`エラーが発生しました: ${response.status}`);
}
// JSON形式のデータに変換
return response.json();
})
.then(data => {
// レスポンスのデータを使う
console.log(`天気: ${data.weather}`);
console.log(`気温: ${data.temperature}度`);
})
.catch(error => {
// エラー処理
console.error("エラー:", error.message);
});
問題
- APIとは何の略で、どのような役割を果たしますか?
答え
Application Programming Interface
- HTTPメソッドのうち、データを新規作成する際に使用するものはどれですか?
答え
POSTメソッド
- APIのエンドポイントとは何ですか?
答え
APIがリクエストを受け付けるための特定のURL
- APIで一般的に使用されるデータ形式は何ですか?
答え
JSON
- APIキーの主な目的は何ですか?
答え
APIキーはアクセス制限やユーザーの認証に使われる。
- HTTPステータスコードで、リクエストが成功したことを示すコードは何ですか?
答え
200
- JavaScriptでJSON文字列をオブジェクトに変換するメソッドは何ですか?
答え
JSON.parse()
- エラーハンドリングとは何ですか?
答え
プログラムの実行中に発生するエラー(例外)を適切に検出し、それに対応する処理を行うことです。
これにより、プログラムのクラッシュを防ぎ、予期しない動作を回避できます。
- 以下のコードで、APIリクエストの結果をJSON形式に変換する部分はどこですか?
fetch(url)
.then(response => {
if (!response.ok) {
throw new Error(`エラーが発生しました: ${response.status}`);
}
return response.json();
})
.then(data => {
console.log(`天気: ${data.weather}`);
console.log(`気温: ${data.temperature}度`);
})
.catch(error => {
console.error("エラー:", error.message);
});
答え
response.json()
参考
Discussion