REST API — 知星図

概要

REST APIは、「ユーザー一覧は GET /users、新規作成は POST /users、42番のユーザーは GET /users/42」のように、操作対象（リソース）をURLで名指しし、操作の種類をHTTPメソッドで表すAPIの設計スタイルです。RESTはRepresentational State Transferの略で、もともとはHTTP仕様の策定にも関わったRoy Fieldingが2000年の博士論文で示したアーキテクチャ原則の名前でした。

新しいプロトコルを発明するのではなく、Webがすでに持っている語彙——URL、HTTPメソッド、ステータスコード——をそのまま設計に活かすのが特徴です。レスポンスの形式にはJSONを使うのが現代の慣習で、「HTTP + JSON + リソース指向のURL」という組み合わせは、Web APIの事実上の標準になっています。

なぜ生まれたか

2000年代初頭、システム間連携の本命とされていたのはSOAPというプロトコルでした。XMLで封筒（エンベロープ）を作り、WSDLという仕様記述言語で契約を定義する重厚な仕組みで、ツールなしには読み書きが困難なほど複雑でした。一方でWebそのものは、シンプルなHTTPとURLだけで惑星規模に成長していました。「この成功したアーキテクチャの原則を、API設計にもそのまま使えばいいのではないか」——Fieldingの論文はWebがなぜスケールしたのかを分析したものであり、RESTはその原則に付けられた名前です。

決定打になったのは学習コストの低さです。RESTふうのAPIは、URLとメソッドを見れば何をするのか推測でき、ブラウザやcurlだけで試せます。2000年代後半、TwitterやAmazonなどがREST形式のAPIを公開してエコシステムを築くと、SOAPは急速に廃れ、「Web APIといえばREST」という時代が訪れました。

詳細

リソースと動詞の対応

RESTの中心にあるのは「名詞はURL、動詞はHTTPメソッド」という分担です。ユーザーというリソースに対するCRUD操作（作成・読み取り・更新・削除）は、次のように4つのメソッドに素直に対応します。

HTTPメソッドとCRUD操作の対応。URLが名詞（リソース）を、メソッドが動詞（操作）を担う

結果の報告にはHTTPステータスコードを流用します。成功なら200番台（作成成功は201）、リクエスト側の誤りなら400番台（未認証は401、権限不足は403、リソース不在は404）、サーバ側の障害なら500番台。独自のエラー体系を発明する代わりに、Webの共通語彙に乗ることで、汎用のツールやキャッシュ、監視の仕組みがそのまま活きます。

ステートレス性という規律

RESTの重要な原則に「ステートレスであること」があります。各リクエストは、それ単体で処理に必要な情報をすべて含んでいなければならず、サーバは「さっきのリクエストの続き」といった会話の文脈を持ちません。この規律のおかげで、どのリクエストをどのサーバが処理しても結果が同じになり、ロードバランサで台数を増やすスケーリングが素直に効きます。認証情報をセッションではなくトークン（JWTなど）で毎回運ぶ設計が好まれるのも、この原則の延長線上にあります。

「RESTっぽさ」の程度問題

Fieldingの論文が定めた原則を厳密に満たすAPIは、実はほとんど存在しません。特にHATEOAS（レスポンスに次に辿れる操作のリンクを含め、クライアントがそれを頼りに遷移する原則）まで実装したAPIは稀です。実務で「REST API」と呼ばれているものの大半は、「リソース指向のURL + HTTPメソッド + JSON」という慣習を押さえた「RESTっぽいAPI」です。成熟度を段階で示すリチャードソン成熟度モデルという物差しもありますが、現場では厳密さより一貫性——命名規則、複数形の統一、エラー形式の統一——のほうがずっと重要です。

設計の勘所と典型的な悩みどころ

実際に設計を始めると、教科書どおりにいかない場面にすぐ出会います。「検索」や「ログイン」のようにリソースに素直に写像できない操作をどうURLにするか。ネストしたリソース（/users/42/posts）をどこまで深くするか。部分更新はPUTかPATCHか。一覧APIのページネーションやフィルタをクエリパラメータでどう表すか。これらに唯一の正解はなく、チームで規約を決めて一貫させることが答えになります。仕様はOpenAPI（Swagger）でスキーマとして記述し、ドキュメントとクライアントコードを自動生成するのが現代の定石です。

RESTの限界とその後継たち

RESTには構造的な弱点もあります。画面に必要なデータが複数リソースにまたがると何往復もリクエストが必要になり（アンダーフェッチ）、逆に固定のレスポンス形式では不要なフィールドまで受け取ってしまいます（オーバーフェッチ）。この課題への応答がGraphQLで、クライアントが「欲しいデータの形」をクエリで指定します。またマイクロサービス間の内部通信のように性能が最優先の場面では、バイナリ形式で通信するgRPCが選ばれます。RESTが消えたわけではなく、「外向けの公開APIはREST、内部通信はgRPC、複雑なフロントエンド向けはGraphQL」のような適材適所の併存が現在の風景です。