🏹

API

2024/12/17に公開

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コード例です。

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);
  });

問題

  1. APIとは何の略で、どのような役割を果たしますか?
答え

Application Programming Interface

  1. HTTPメソッドのうち、データを新規作成する際に使用するものはどれですか?
答え

POSTメソッド

  1. APIのエンドポイントとは何ですか?
答え

APIがリクエストを受け付けるための特定のURL

  1. APIで一般的に使用されるデータ形式は何ですか?
答え

JSON

  1. APIキーの主な目的は何ですか?
答え

APIキーはアクセス制限やユーザーの認証に使われる。

  1. HTTPステータスコードで、リクエストが成功したことを示すコードは何ですか?
答え

200

  1. JavaScriptでJSON文字列をオブジェクトに変換するメソッドは何ですか?
答え

JSON.parse()

  1. エラーハンドリングとは何ですか?
答え

プログラムの実行中に発生するエラー(例外)を適切に検出し、それに対応する処理を行うことです。
これにより、プログラムのクラッシュを防ぎ、予期しない動作を回避できます。

  1. 以下のコードで、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()

参考

https://www.digitalocean.com/community/tutorials/js-json-parse-stringify-ja

Discussion