PRプログラミング

APIの基本｜HTTP・JSON・fetchを初めて学ぶ人の確認ポイント

アプリの画面に情報を表示するとき、別のサービスへデータを問い合わせることがあります。APIは、決められた方法で機能やデータを利用するための窓口です。最初は難しい認証や実サービスへの接続より、送る内容と返る内容を分けて考えましょう。

この記事では、ブラウザーのfetchを使う基本を紹介します。コードのURLは自分の練習環境に用意するファイルを指す例で、ミラナビに実装されているAPIではありません。

リクエストとレスポンスを分ける

HTTPで問い合わせるときは、宛先のURL、GETなどのメソッド、必要に応じたヘッダーや本文を組み合わせます。返ってくるレスポンスでは、状態を示すステータスや本文を確認します。画面へ出す情報だけでなく、どんな条件で利用できるかもAPIの説明で確かめる必要があります。

最初の練習では、更新や削除より読み取りだけの処理に絞ると結果を確認しやすくなります。実サービスを使う段階では、利用規約、回数の制限、料金、取得した情報の扱いを確認してください。アクセスできたことと、自由に再利用できることは別に考えましょう。

JSONの項目と値を確かめる

JSONは、データをやり取りするときに使われる形式の一つです。例として次の内容を「sample.json」に保存し、練習用のWebサーバーから取得できるようにします。ファイルを直接開く方式では、ブラウザーの制約により同じコードが動かない場合があります。教材が案内するローカルサーバーを使ってください。

{
  "title": "読書メモ",
  "count": 3
}

この例ではtitleが文字列、countが数値です。受け取ったデータを使う前に、想定した項目が存在するか、値の種類が合うかを確認します。実際のAPIでは配列になっていたり、データが別の項目の中に入っていたりするため、見た目だけで形式を決めつけないようにしましょう。

fetchで取得し、状態を確認する

次の例は、同じ練習サイトにあるsample.jsonを取得します。fetchは非同期の処理なので、async関数の中でawaitを使って応答を待ちます。HTTPの応答を確認してからJSONとして読み、コンソールへ表示します。

async function loadSample() {
  try {
    const response = await fetch("./sample.json");
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    const data = await response.json();
    console.log(data.title, data.count);
  } catch (error) {
    console.error("取得できませんでした", error);
  }
}

loadSample();

fetchは、404などのHTTPエラーステータスだけでは通常rejectされません。そのためresponse.okやstatusを確認します。通信の失敗やJSONを読めない場合もあり、取得できない状態を扱う処理を考える必要があります。

参考：MDN「Fetch API の使用」

認証情報と公開範囲を確認する

ブラウザーで配信するJavaScriptに、秘密にする必要のあるAPIキーを埋め込まないようにします。利用者が読めるコードや送信内容に含まれるためです。実サービスの認証方式に従い、秘密情報が必要な場合はサーバー側の構成などを検討してください。

また別のドメインへの通信では、CORSなどの条件が関係します。通信できないからといって、理由の分からない回避策を重ねるのではなく、サービスがブラウザーからの利用を認めているかを確認します。まず手元のサンプルで取得の流れを理解し、外部APIの条件は別に調べましょう。

  1. 自分のサンプルを取得して形式を確認する
  2. HTTPの状態と失敗時の表示を考える
  3. 実APIの仕様と利用条件を読む
  4. 認証情報をどこで扱うか設計する

よくある質問

Q. URLをブラウザーで開ければfetchでも使えますか？

必ずしも同じ条件ではありません。認証、CORS、返される形式などの違いで、プログラムからの取得に条件が付く場合があります。開発者ツールで通信と応答を確認し、APIの公式説明と照らし合わせましょう。

Q. JSONを読めればデータは正しいですか？

JSONとして解釈できても、必要な項目や値がそろっているとは限りません。項目の有無や種類、想定する範囲を確認する処理も必要です。まず練習の例で形を理解し、実データでは仕様に合わせて検証してください。

実践前のチェックリスト

  1. 問い合わせるURLと方法を確認した
  2. JSONの項目と値の種類を読んだ
  3. HTTPの状態を確認した
  4. 取得できない場合を試した
  5. 認証情報の公開範囲を確認した

まとめ

APIの基本は、問い合わせる内容と返ってくる状態・データを分けて読むことです。まず自分のJSONファイルをfetchで取得し、成功と失敗の両方を確かめましょう。外部サービスへ進むときは、利用条件と認証情報の扱いも合わせて確認してください。

関連記事