API設計

RESTful API れすとふるえーぴーあい

RESTHTTPWeb APIJSONエンドポイントステートレス

RESTful APIについて教えて

簡単に言うとこんな感じ！

WebサービスどうしがHTTPで「情報をやり取りするときのお作法」だよ！「この住所に来たらこのデータを返す」ってルールを決めておくことで、スマホアプリもPCも同じ窓口でデータを受け取れるんだ！

RESTful APIとは

RESTful API（レストフルエーピーアイ）とは、REST（Representational State Transfer）というアーキテクチャスタイルの原則に従って設計されたWeb APIのことです。API（Application Programming Interface）とは、ソフトウェアどうしが会話するための「窓口」のようなもので、RESTfulはその窓口の設計ルールを指します。

たとえば「商品一覧を取得したい」「注文を新規登録したい」「ユーザー情報を更新したい」といった操作を、HTTPのURL（エンドポイント）とメソッド（GET・POST・PUT・DELETEなど）の組み合わせで表現するのがRESTful APIの特徴です。スマートフォンアプリ、Webブラウザ、他社サービスなど、異なる環境からでも同じルールで呼び出せるため、現代のWebサービス開発で広く採用されています。

「RESTfulかどうか」は単なる言葉の問題ではなく、設計品質の指標でもあります。RESTの原則に沿った設計は保守しやすく、開発チームが増えても混乱しにくいため、システム発注・選定の場面でも「RESTful APIで提供されているか」は重要な確認ポイントになります。

RESTの6つの原則

RESTには設計上守るべき原則があります。これを理解しておくと、「このAPIはきちんと設計されているか」を判断する目安になります。

原則	概要	ビジネス的な意味
クライアント・サーバー分離	画面側（クライアント）とデータ側（サーバー）を切り離す	フロントとバックエンドを独立して改修できる
ステートレス	リクエストは毎回完結。サーバーは状態を保持しない	スケールアウト（サーバー増設）が容易
キャッシュ可能	レスポンスをキャッシュ（一時保存）してよいか明示する	通信量削減・高速化
統一インターフェース	URLとHTTPメソッドで操作を統一する	開発者が直感的に使える
階層化システム	中間にプロキシ・ロードバランサーを挟んでよい	セキュリティ・可用性の向上
コードオンデマンド（任意）	サーバーが実行可能コードを返してもよい	JavaScriptの動的配信など（省略可）

覚え方：「クス・キャ・統・階・コ」

「クス（クライアント・サーバー）・ス（ステートレス）・キャ（キャッシュ）・統（統一インターフェース）・階（階層化）・コ（コードオンデマンド）」と頭文字でまとめると6原則が整理しやすいです。

HTTPメソッドとCRUD操作の対応

RESTful APIではCRUD（Create・Read・Update・Delete）という4種類のデータ操作を、HTTPメソッドに対応させます。

HTTPメソッド	操作	例（商品APIの場合）
`GET`	取得（Read）	`GET /products` → 商品一覧を取得
`POST`	新規作成（Create）	`POST /products` → 商品を登録
`PUT` / `PATCH`	更新（Update）	`PUT /products/1` → 商品ID:1を更新
`DELETE`	削除（Delete）	`DELETE /products/1` → 商品ID:1を削除

歴史と背景

2000年 — ロイ・フィールディング（Roy Fielding）がUC Irvineの博士論文でRESTを提唱。HTTPの設計者の一人でもある
2000年代前半 — SOAP（ソープ）という複雑なXMLベースのAPIが主流だったが、冗長で扱いにくいと批判を受ける
2004〜2006年頃 — Flickr・Amazonが軽量なREST APIを公開し注目を集める。Web 2.0ブームと連動して普及加速
2007〜2010年 — Twitter・FacebookがREST APIを提供。サードパーティアプリ連携のデファクトスタンダードに
2010年代 — スマートフォン普及でモバイルアプリとサーバー間通信の需要が爆発。JSON（ジェイソン）がデータ形式の主流となり、REST APIの開発コストがさらに低下
2015年以降 — GraphQL・gRPCなど新しいAPIスタイルも登場するが、REST APIは現在も最も広く使われる標準的な選択肢

RESTful API vs 他のAPIスタイル

現在よく使われるAPIスタイルを比較します。発注・選定時に「なぜRESTfulを選ぶのか」を説明できるようになります。

エンドポイント設計の良い例・悪い例

RESTfulな設計かどうかは、URLの作り方で一目でわかります。

【良い例：名詞ベースのURL】
GET    /users          → ユーザー一覧を取得
GET    /users/42       → ID:42のユーザーを取得
POST   /users          → ユーザーを新規作成
PUT    /users/42       → ID:42のユーザーを全更新
DELETE /users/42       → ID:42のユーザーを削除

【悪い例：動詞がURLに入っている】
GET    /getUser?id=42
POST   /createUser
POST   /deleteUser?id=42   ← DELETEメソッドを使うべき

規格・RFC番号	内容
RFC 9110	HTTP Semantics（HTTPの意味論的定義。RESTful APIの基盤）
RFC 9112	HTTP/1.1（RESTful APIで最も広く使われるプロトコル）
RFC 7159	JSON（RESTful APIのデータ形式として標準的に使われる）
RFC 7807	Problem Details for HTTP APIs（エラーレスポンスの標準形式）
RFC 6750	OAuth 2.0 Bearer Token（REST APIの認証で広く使われる）