REST API

Representational State Transfer API

Web開発

RESTは、クライアント・サーバー、ステートレス、キャッシュ、統一されたインターフェースなどの制約を組み合わせた設計様式です。REST APIはその考え方を踏まえたAPIを指します。HTTPでJSONを返すだけで、すべてのRESTの制約を満たすとは限りません。

🐾 猫で例えると？

アメショと茶トラがお互いの腕と背中を枕にしてリソースをシェアして眠る様子 — お互いのリソースを上手に共有し合うWin-Winな連携

寄り添う2匹は、相手の持つものを利用する連携のイメージです。ただし猫が密着する様子でREST固有の性質までは表せません。たとえば「猫の情報」を操作の対象（リソース）としてURLで区別し、名前や毛色などのデータを取得・更新する、と具体化して考えましょう。

💻 IT現場における「REST API」とは？

RESTの考え方では、表示や操作を担う側と、資源を提供する側の関心を分けます。別々に開発しやすくなる一方、データ形式や認証、失敗時の扱いといった契約は双方で合わせる必要があります。

HTTPを使うAPIでは、GETは取得、PUTは対象資源の置換など、メソッドの意味を尊重します。GETで注文の確定などの変更操作を行わないことが一例です。独自の業務ルールまでHTTPだけで決まるわけではありません。

⚠️ REST APIの仕組みと注意点

リソースを表す名詞のURLは分かりやすい設計上の慣例ですが、複数形かどうかだけでRESTを判定することはできません。統一インターフェースには、自己記述的なメッセージや、表現内のリンクを通じた状態遷移といった制約も含まれます。

API通信での実装例

次はHTTPのGETでJSONを取得する説明用コードです。example.comのURLは仮の宛先なので、そのままユーザー情報が取得できるサービスではありません。実際のAPI仕様と認証条件に合わせて置き換えます。

// JavaScript (Fetch API) でのREST APIリクエスト例
fetch('https://api.example.com/users/123') // ユーザーID:123のリソースを指定
  .then(response => {
    if (!response.ok) {
      throw new Error('データの取得に失敗しました');
    }
    return response.json(); // JSON形式のデータを抽出
  })
  .then(userData => {
    console.log('取得したユーザー情報:', userData);
  })
  .catch(error => console.error('エラー:', error));

このコードはHTTP API呼び出しの一部分を示しています。サーバーが前回の会話の文脈を覚えていなくても要求を解釈できることと、商品や注文などのデータをDBに保存することは両立します。

🛠️ REST APIを賢く使うためのポイント

複数人でシステムを開発する現場では、誰が見ても分かりやすいREST APIの設計がプロジェクトの成功を左右します。

直感的なエンドポイント設計： URLは名詞の複数形を基本とし、階層構造（例：`/users/123/orders`）を利用してリソース間の関係性を明確にする。
適切なステータスコードの返却： 成功時は200番台、クライアント側のエラーは400番台、サーバー側のエラーは500番台を正しく使い分ける。
APIのバージョニング： 将来の仕様変更に備えて、URLにバージョン情報を含める（例：`/v1/users`）などし、後方互換性を保つ工夫をする。

お互いの場所を使い分ける猫たちのように、REST APIでも対象と操作の役割を整理します。URLで何を表し、HTTPメソッドでどの操作を行うか、失敗時に何を返すかをそろえると、利用する側が動きを予想しやすくなります。