RESTful APIとは

API の設計スタイルの一つである RESTful API について、基本的な考え方を整理します。

1. RESTful APIの概要

RESTful APIとは、APIを設計する際に広く採用されている設計原則(ルール)のことです。REST(Representational State Transfer)という設計思想に基づいて作られたAPIを、RESTful APIと呼びます。

ここまでの説明で、HTTP通信の仕組み(メソッド、パス、ステータスコード、ヘッダ、ボディ)やAPIの概念について学んできました。RESTful APIは、これらの仕組みを「どのように組み合わせてAPIを設計すべきか」を示すガイドラインです。

たとえば、タスク管理アプリケーションのAPIを作るとき、「タスクの一覧を取得するにはどんなURLにどんなメソッドでリクエストすればいいのか」「新しいタスクを作成するにはどうすればいいのか」といった設計の指針を、RESTful APIの原則が提供してくれます。

RESTful APIは、主に以下の5つの原則で構成されています。

  • クライアントとサーバの分離(Client-Server)
  • 統一されたインタフェース(Uniform Interface)
  • ステートレス(Stateless)
  • キャッシュ可能性(Caching)
  • 階層化された構造(Layered System)

それぞれの原則について、具体的な事例を交えながら説明していきます。

📝 設計原則の表現について
これらの設計原則は、書籍やWebサイトによって表現の仕方や解釈に微妙な違いが見られることがありますが、基本的な考え方や目的は同じです。細かな言葉の違いにとらわれすぎないことが重要です。

2. クライアントとサーバの分離

RESTful APIの1つ目の原則は、クライアント(フロントエンド)とサーバ(バックエンド)を分離することです。両者の通信はHTTPのリクエストとレスポンスのみで行います。

たとえば、ECサイトを例に考えてみます。クライアントとサーバが分離されていない構成では、商品の表示画面とデータベースの処理が一つのシステムに含まれています。この場合、商品画面のデザインを変更しただけで、データベース処理にも予期せぬ影響が出てしまう可能性があります。

一方、クライアントとサーバが分離されている構成では、フロントエンド(商品画面の表示)とバックエンド(商品データの管理)がそれぞれ独立したシステムとして動作します。フロントエンドが商品データを必要とする場合は、バックエンドのAPIに対してHTTPリクエストを送信し、レスポンスとしてJSON形式のデータを受け取ります。

この分離により、以下のメリットが得られます。

  • フロントエンドとバックエンドを別々のチームで開発できる
  • フロントエンドのデザイン変更がバックエンドに影響しない(その逆も同様)
  • 同じAPIをWebアプリケーション・スマホアプリケーション・外部サービスなど複数のクライアントから利用できる

3. 統一されたインタフェース

RESTful APIの2つ目の原則は、HTTPメソッドとパスの組み合わせで操作を統一的に表現することです。

HTTPメソッドとCRUD操作の対応を図に示します。

まず、リソースという概念を理解しましょう。リソースとは、APIで操作を行う対象のことです。たとえば、タスク管理アプリケーションであれば「タスク」がリソースになり、ECサイトであれば「商品」や「注文」がリソースになります。RESTful APIでは、リソースはパスで表現し、複数形(tasks、products、ordersなど)で定義するのが一般的です。

このリソースに対して、HTTPメソッドを組み合わせることで「何を」「どうするか」を表現します。タスク管理アプリケーションのtasksリソースを例に見てみましょう。

HTTPメソッド パス 操作 説明
GET /tasks 一覧取得 タスクの一覧を取得する
GET /tasks/{id} 詳細取得 特定のタスクを取得する
POST /tasks 作成 新しいタスクを作成する
PUT /tasks/{id} 更新 特定のタスクを更新する
DELETE /tasks/{id} 削除 特定のタスクを削除する

この設計の優れている点は、リソースが変わってもルールが同じであることです。たとえば、同じアプリケーションに「ユーザ」リソースを追加する場合も、まったく同じパターンで設計できます。

HTTPメソッド パス 操作
GET /users ユーザの一覧を取得する
POST /users 新しいユーザを作成する
DELETE /users/{id} 特定のユーザを削除する

このように統一されたルールに従うことで、APIの利用者はドキュメントを細かく確認しなくても、「GET /productsは商品の一覧を取得するのだろう」「DELETE /orders/5はIDが5の注文を削除するのだろう」と直感的に理解できます。

4. ステートレス

RESTful APIの3つ目の原則は、ステートレス(状態を持たない)であることです。これは、サーバがクライアントの状態を記憶しないことを意味します。各リクエストはそれ単体で完結しており、サーバは「このクライアントは前回何をリクエストしたか」といった情報を保持しません。

身近な例で考えてみましょう。レストランの注文を想像してください。

  • ステートフル(状態を持つ)な注文方式は、常連客を覚えている店員のようなものです。「いつもの」と言えば前回と同じ注文が通りますが、店員が変わると「いつもの」が通じなくなります。
  • ステートレスな注文方式は、毎回メニュー表から注文する方式です。誰が対応しても同じサービスを受けられます。

RESTful APIでは、このステートレスな方式を採用します。たとえば認証が必要なAPIの場合、クライアントは毎回のリクエストに認証情報(トークン)を含めて送信します。

GET /tasks HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

サーバは「このクライアントはログイン済みだ」という情報を保持するのではなく、リクエストに含まれるトークンを毎回検証して認証を行います。これにより、以下のメリットが得られます。

  • どのサーバがリクエストを処理しても同じ結果が返せるため、負荷分散が容易になる
  • サーバがクライアントの状態を管理する必要がないため、サーバの処理が簡略化される
  • サーバを複数台に増やしても、サーバ間で状態を共有する必要がない

5. キャッシュ可能性

RESTful APIの4つ目の原則は、キャッシュ(データの一時保存)を適切に活用することです。

たとえば、ニュースサイトのトップページを考えてみましょう。記事の一覧データは数分間ほとんど変わりません。にもかかわらず、ユーザがページを開くたびにサーバに問い合わせていたら、サーバへの負荷が不必要に増大してしまいます。そこで、一度取得したデータを一時的に保存しておき、次回アクセス時にはその保存データを再利用する仕組みがキャッシュです。

RESTful APIでは、レスポンスヘッダのCache-Controlによってキャッシュの有効期限を指定します。

Cache-Control: max-age=300

この例では、「このレスポンスを300秒(5分間)キャッシュしてよい」とクライアントに指示しています。5分以内に同じリクエストが発生した場合、クライアントはサーバに問い合わせることなく、保存されたデータを再利用できます。

6. 階層化された構造

RESTful APIの5つ目の原則は、クライアントとサーバの間に中間層(レイヤ)を配置できる構造にすることです。

たとえば、人気のあるWebサービスでは、大量のリクエストを1台のサーバで処理することは困難です。そこで、クライアントとAPIサーバの間にロードバランサを配置し、リクエストを複数のサーバに振り分けます。

この構成のポイントは、クライアントがロードバランサの存在を意識する必要がないことです。クライアントから見れば、1つのURLにリクエストを送っているだけで、裏側で複数のサーバに振り分けられていることを知る必要はありません。ロードバランサ以外にも、CDN(コンテンツ配信ネットワーク)や認証サーバなどを中間層として配置することができます。

📝 直接アクセスの制限
中継システム経由でのアクセスに限定したい場合は、セキュリティグループやファイアウォールを用いてAPIへの直接アクセスを制限することが有効です。

7. RESTful APIのまとめ

ここまで5つの原則を見てきましたが、RESTful APIを一言でまとめると、「HTTPの仕組み(メソッド・パス・ステータスコードなど)を活用して、わかりやすく・拡張しやすいAPIを設計するためのルール」です。

たとえば「タスクの一覧を取得したい」ならGET /tasks、「新しいタスクを作成したい」ならPOST /tasksというように、HTTPの仕組みをそのまま活かして直感的にAPIを設計できる点がRESTful APIの大きな特徴です。

RESTful APIの5つの原則をまとめると以下のとおりです。

原則 概要
クライアントとサーバの分離 フロントエンドとバックエンドを独立させ、HTTPで通信する
統一されたインタフェース HTTPメソッドとパスの組み合わせで操作を統一的に表現する
ステートレス サーバはクライアントの状態を保持せず、各リクエストを独立して処理する
キャッシュ可能性 レスポンスをキャッシュして不要な通信を削減する
階層化された構造 クライアントとサーバの間にロードバランサなどの中間層を配置できる