はじめに

この記事では、Web APIの基礎について学びます。APIとは何か、どのように使うのか、そして実際にAPIを呼び出す方法まで、初心者の方でも理解できるように解説していきますね。

この記事で学べること

APIの基本概念とWeb APIの仕組み
HTTPメソッドの種類と使い分け
リクエストとレスポンスの構造
実際のAPI呼び出し方法

対象読者

Web APIについて初めて学ぶ方
JavaScriptでAPIを使ってみたい方
バックエンドとフロントエンドの連携について知りたい方

APIとは何か

APIの基本概念

APIは Application Programming Interface の略です。簡単に言えば、異なるソフトウェア同士が情報をやり取りするための窓口のことですね。

APIには様々な種類がありますが、この記事では特に Web API について扱います。Web APIとは、HTTPを通じて利用できるAPIのことで、インターネット経由でデータの取得や送信ができます。

Web APIとエンドポイント

Web APIでは、特定のURLに対してリクエストを投げることでデータを取得します。このリクエスト先のURLをエンドポイントと呼びます。

例えば、以下のようなイメージです。

APIが提供されているということは、その背後にサーバーが存在し、運用コストがかかっています。そのため、無料で使えるAPIは限られていることを覚えておきましょう。

AJAXとWeb API

従来のWebページでは、ページ全体を再読み込みしてデータを取得していました。しかし、AJAXという技術を使うと、同じページに滞在したまま裏側でデータを取得できます。

AJAXでは、JavaScriptからデータリクエストを投げると、JSONなどのデータ形式でレスポンスを受け取ることができます。これにより、ページをリロードせずに動的にコンテンツを更新できるようになりました。

HTTPメソッドを理解しよう

APIとやり取りする際には、目的に応じて適切なHTTPメソッドを使い分ける必要があります。主要なメソッドを見ていきましょう。

GET - データの取得

GETリクエストは、データを取得するためのリクエストです。実は、ブラウザのURLバーにURLを入力してアクセスするのもGETリクエストなんですね。

サーバー上のデータを変更せず、単に情報を読み取るだけの場合に使用します。

POST - データの送信

POSTリクエストは、サーバーにデータを送信するためのリクエストです。フォームの送信やユーザー登録など、新しいデータを作成する場合に使われます。

PUT - データの更新

PUTリクエストは、既存のデータを更新するためのリクエストです。例えば、ユーザー情報の編集などで使用されます。

DELETE - データの削除

DELETEリクエストは、データを削除するためのリクエストです。その名の通り、サーバー上のデータを削除する際に使用します。

その他のHTTPメソッド

HEAD、OPTIONS、PATCHなどのメソッドも存在します。ただし、APIの実装によって対応しているメソッドが異なるため、全てのAPIが全てのHTTPメソッドに対応しているわけではありません。

リクエストとレスポンスの詳細

ステータスコードの読み方

APIからのレスポンスには、ステータスコードが含まれています。これは3桁の数字で表され、リクエストの結果を示します。

1xx: 情報レスポンス（処理継続中）
2xx: 成功レスポンス（リクエストが正常に処理された）
3xx: リダイレクトレスポンス（別のURLへの転送）
4xx: クライアントエラー（リクエストに問題がある）
5xx: サーバーエラー（サーバー側で問題が発生）

パスパラメーターの使い方

APIのエンドポイントには、パスパラメーターが含まれることがあります。パスパラメーターは{}で囲まれた部分で、動的な値を表します。

例えば、/users/{id}というエンドポイントがある場合、{id}はユーザーのIDを表すパスパラメーターです。実際にリクエストを投げるときには、この部分を具体的な値に置き換えます。

例: /users/123 → IDが123のユーザーを取得

クエリパラメーターの使い方

クエリパラメーターは、?マークの後ろに続く部分で、APIに対して追加の情報を渡すために使います。

例: /users?age=30&gender=male

この例では、ageとgenderがクエリパラメーターです。クエリパラメーターは&で区切られ、key=valueの形式で表されます。

クエリパラメーターは省略可能な場合が多く、フィルタリングや並び替えなどのオプション指定に使われます。

HTTPヘッダーの役割

HTTPヘッダーは、クライアントからサーバーへ情報を送信するために使われます。例えば、以下のような情報を含めることができます。

認証情報（APIキーやトークン）
コンテンツタイプ（送信するデータの形式）
言語設定

APIによっては、特定のヘッダーが必須になることもあります。例えば、Authorizationヘッダーを使ってAPIキーを送信するケースがよくあります。

JSONデータフォーマット

JSONとは

JSONは JavaScript Object Notation の略で、データをやり取りする際の標準的なフォーマットです。

以前はXMLが使われていましたが、JSONの方が軽量で扱いやすいため、現在はJSONが主流になっています。

JSONの特徴として、以下の点を覚えておきましょう。

文字列として扱われる
undefinedや関数は含めることができない
nullは使用可能だが、undefinedとの違いに注意が必要

JSON.parse()とJSON.stringify()

JavaScriptでJSONを扱う際には、以下の2つのメソッドを使います。

JSON.parse() - JSON文字列をJavaScriptオブジェクトに変換

const jsonString = '{"name": "太郎", "age": 25}';
const obj = JSON.parse(jsonString);
console.log(obj.name); // "太郎"

JSON.stringify() - JavaScriptオブジェクトをJSON文字列に変換

const obj = { name: "太郎", age: 25 };
const jsonString = JSON.stringify(obj);
console.log(jsonString); // '{"name":"太郎","age":25}'

実際にAPIを使ってみよう

hoppscotchでAPIを試す

実際にコードを書く前に、APIの動作を確認できるツールがあります。hoppscotchは、ブラウザ上でAPIリクエストを試すことができる便利なツールです。

hoppscotchを使えば、以下のようなことができます。

GETリクエストを投げてデータを取得
POSTリクエストを投げてデータを送信
ヘッダーやパラメーターの設定

まずはこのツールでAPIの動作を確認してから、コードを書いていくのがおすすめですね。

JavaScriptでAPIを呼び出す

JavaScriptでAPIを呼び出す方法はいくつかありますが、ここでは代表的な2つの方法を紹介します。

XMLHttpRequest（参考）

XMLHttpRequestは、古くからあるAPI呼び出しの方法です。現在では後述する新しい方法が推奨されていますが、歴史を知るために覚えておくと良いでしょう。

XMLHttpRequestはPromiseもサポートしていないため、現在ではほとんど使われていません。

fetch APIの使い方

fetch APIは、現代的なAPI呼び出しの標準的な方法です。Promiseベースで動作するため、非同期処理を扱いやすくなっています。

// 基本的な使い方
fetch('https://api.example.com/users')
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('エラー:', error);
  });

// async/awaitを使った書き方
async function getUsers() {
  try {
    const response = await fetch('https://api.example.com/users');
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('エラー:', error);
  }
}

fetch APIでは、結果がPromiseオブジェクトとして返却されます。順番に処理を実行する必要がある場合も、きれいに書くことができますね。

AXIOSライブラリの紹介

AXIOSは、人気のあるHTTPクライアントライブラリです。fetch APIよりも多機能で使いやすいという特徴があります。

AXIOSの主な利点は以下の通りです。

ブラウザとNode.jsの両方で動作
fetch APIと違い、自動的にJSONに変換してくれる
リクエストのキャンセルやタイムアウト設定などの便利な機能

使用するには、事前にインストールが必要です。

npm install axios

// AXIOSの使用例
import axios from 'axios';

async function getUsers() {
  try {
    const response = await axios.get('https://api.example.com/users');
    console.log(response.data); // 既にJSONに変換されている
  } catch (error) {
    console.error('エラー:', error);
  }
}

fetch APIではresponse.json()を明示的に呼ぶ必要がありましたが、AXIOSではresponse.dataで直接データにアクセスできます。

まとめ

この記事では、Web APIの基礎について学びました。重要なポイントをおさらいしましょう。

APIは異なるソフトウェア同士が情報をやり取りするための窓口
HTTPメソッドを使い分けることで、データの取得・送信・更新・削除を行える
ステータスコードでリクエストの結果を確認できる
パスパラメーターとクエリパラメーターで柔軟なリクエストが可能
JSONは現代のWeb APIで標準的なデータフォーマット
fetch APIやAXIOSを使ってJavaScriptからAPIを呼び出せる

まずはhoppscotchなどのツールでAPIの動作を確認し、その後実際にコードを書いてみることをおすすめします。最初は無料で使えるパブリックAPIを探して、色々試してみると良いでしょう。

参考リンク