Rest Api

「REST API」とは結局何を指すのか？

多くの開発現場、特にWebサービスやアプリケーション開発に足を踏み入れたばかりの頃、「API」という言葉はまるで「魔法の箱」のように聞こえる。特定のURL（エンドポイントと呼ばれる）にリクエストを送ると、必要なデータがJSON形式で返ってくる。便利な仕組みだが、その実態を深く理解しているだろうか。

多くの現場で「REST API」と呼ばれているものは、実際には「HTTPを使ってJSONを返すAPI」程度の意味で使われていることが多い。しかし、「REST」という言葉には、提唱者が込めた強固な設計思想が存在する。

この記事の目的は、「REST」が本来目指したものは何だったのか、その原則と具体的な設計手法、そしてなぜ多くの現場でその「理想」が採用されないのか、という「現実」を解き明かすことである。

1. そもそも「API」と「HTTP」とは何か？

RESTの解説の前に、その土台となる「API」と「HTTP」の概念を正確に掴む必要がある。

API (Application Programming Interface)

APIとは、直訳すれば「アプリケーションをプログラミングするためのインターフェース（接点）」だ。 **「ソフトウェア同士が会話するための”窓口”であり、その”会話のルール”」**だと考えればよい。

例えば、天気予報アプリが、気象庁のサーバーにある最新の天気データを取得したい場合、気象庁が「この窓口（URL）に、こういう形式（例：『東京』という地名）で話しかけてくれれば、天気データを渡しますよ」というルールを決めて公開する。この「窓口」と「ルール」のセットがAPIである。

HTTP (HyperText Transfer Protocol)

では、Webにおける「会話のルール」とは何だろうか。それが HTTP である。 HTTPは、Webサーバーとクライアント（我々が使うブラウザなど）がデータをやり取りするための基本的なプロトコル（通信規約）だ。

初心者にとって重要なのは、HTTPが「何をしたいか」を伝えるための 「メソッド（動詞）」　を持っていることだ。最も重要な2つをまず覚えよう。

GET: データを　「取得したい（欲しい）」　と伝える。
- 例: ブラウザがWebページを表示するために、サーバーからHTMLファイルや画像をもらう。
POST: データを　「送信したい（登録したい）」　と伝える。
- 例: フォーム（問い合わせ、会員登録など）に入力した内容をサーバーに送る。

つまり、Web API（特にREST API）とは、　「HTTPという世界共通の会話ルールを使って、アプリケーション同士がデータのやり取り（取得や登録）をするための窓口」　に他ならない。

2. 「REST」が解決しようとしたもの

APIの基本がわかったところで、本題の「REST」に進もう。

REST（REpresentational State Transfer）は、2000年にロイ・フィールディング氏の博士論文で提唱された、ネットワーク・アプリケーション（特にWeb）のための　設計思想（アーキテクチャスタイル）　である。

重要なのは、RESTが特定の技術や規格（「JSONを使うこと」など）を指すのではないという点だ。それは「設計の原則（ルールセット）」である。

フィールディング氏は、巨大で複雑化し続けるWeb（World Wide Web）が、なぜうまく機能し続けているのかを分析し、その「Webらしさ」を支える原則を抽出した。そして、「Webの成功原理（HTTPやURI）を正しく、最大限に活用する」ことで、柔軟でスケールしやすい（拡張しやすい）システムを設計できると考えた。これがRESTの根本思想である。

RESTが登場する前は、RPC（Remote Procedure Call）のように、独自の複雑なルールで通信するAPIが多かった。それに対し、RESTは「Webには既にHTTPという素晴らしい仕組みがあるのだから、それにもっと素直に従うべきだ」と提唱したのだ。

3. 「REST API」を構成する原則

では、具体的に「RESTの原則」に従ったAPIとはどのようなものか。いくつかの重要な原則があるが、ここでは現代のAPI設計で最も基礎となる「URI」と「HTTPメソッド」の役割分担に焦点を当てる。

原則1：URI（リソース） - 「何を」

RESTでは、APIが操作対象とする全ての「モノ」や「情報」を**「リソース（Resource）」**と呼ぶ。そして、そのリソースは URI (Uniform Resource Identifier) によって、一意の「住所」を与えられるべきとされる。

良い例（RESTの考え方）:

/users/123 （IDが123のユーザー）

/posts （投稿のコレクション）

/products/abc-001 （商品コードabc-001の商品）

RESTのURIは、操作対象の「名詞」であるべきである。

悪い例:

/getUser

/createPost

/updateProduct

これらは「住所」ではなく「操作（動詞）」になってしまっている。

原則2：HTTPメソッド（操作） - 「どうする」

URIが「名詞（住所）」を定義したなら、「操作（動詞）」はHTTPメソッドが担うべき、というのがRESTの考え方だ。

先程のGET（取得）とPOST（送信）に加え、RESTでは以下のメソッドも積極的に活用する。

HTTPメソッド	意味（操作）
GET	リソースの取得
POST	リソースの新規作成（子リソースとして）
PUT	リソースの完全な置換（更新）
DELETE	リソースの削除

これらの原則を組み合わせると、APIの設計は非常に統一的かつ直感的になる。

例：「ユーザー」リソースの操作

ユーザー(ID: 123) を取得する
- GET /users/123
新しいユーザーを作成する
- POST /users (リクエストボディに新しいユーザー情報をJSONで送る)
ユーザー(ID: 123) の情報を更新する
- PUT /users/123 (リクエストボディに更新後の全情報をJSONで送る)
ユーザー(ID: 123) を削除する
- DELETE /users/123

このように、「何を（URI）」と「どうする（HTTPメソッド）」を分離することで、APIの利用者は（/users というリソースがあることさえ知れば）HTTPの標準ルールに従って操作を推測できる。これがRESTの目指した「統一インターフェース」の基本である。

4. RESTの理想：「HATEOAS」という頂

ここまでの解説は、多くの「REST API入門」で語られる内容だ。しかし、これだけではRESTの設計思想の半分も理解したことにならない。

フィールディング氏が提唱したRESTの原則の中で、最も重要かつ、現代のAPIのほとんどで無視されている原則がある。それが HATEOAS (Hypermedia as the Engine of Application State) である。

日本語に訳すと「アプリケーション状態のエンジンとしてのハイパーメディア」となるが、これでは何のことか分からない。

簡単に言えば、　「APIレスポンス自体が、クライアントが次に何をできるかを教えるべきだ」　という原則だ。

HATEOASがないAPI

例えば、/users/123 の情報を取得したとする。

// GET /users/123 のレスポンス
{
  "id": 123,
  "name": "Yamada Taro",
  "department_id": 45
}

このユーザーが所属する部署（department_id: 45）の情報を知りたい場合、クライアント（API利用者）はどうすればよいか？

クライアントは「APIドキュメント（仕様書）」を読み、「ふむふむ、部署の情報は GET /departments/{id} で取れるのか。じゃあ /departments/45 にアクセスすればいいな」と判断する必要がある。

これは、クライアントが「URIの構造（/departments/{id}）」を事前に知っていることを前提としており、クライアントとサーバーが密結合している状態だ。もしサーバー側がURIを /depts/{id} に変更したら、クライアントアプリは動かなくなる。

HATEOASがあるAPI（RESTの理想）

HATEOASの原則に従うと、レスポンスは以下のようになる。

// GET /users/123 のレスポンス (HATEOASあり)
{
  "id": 123,
  "name": "Yamada Taro",
  "department_id": 45,
  "_links": {
    "self": {
      "href": "https://api.example.com/users/123"
    },
    "department": {
      "href": "https://api.example.com/departments/45"
    },
    "edit": {
      "href": "https://api.example.com/users/123",
      "method": "PUT"
    },
    "delete": {
      "href": "https://api.example.com/users/123",
      "method": "DELETE"
    }
  }
}

このレスポンスは、_links というセクションを含んでいる。クライアントは、部署情報が欲しければ、ドキュメントを読まずとも _links.department.href にあるURL (/departments/45) にアクセスすればよい。ユーザーを削除したければ _links.delete.href に DELETE メソッドでリクエストすればよい。

サーバーは「次にできること」をURLで示し、クライアントはそれに従うだけだ。これが「ハイパーメディア（リンク）がアプリケーションの状態（次何をすべきか）を駆動する（エンジン）」という意味である。

HATEOASの利点:

疎結合: サーバーはURI構造を自由に変更できる。クライアントはレスポンス内のURLに従うだけなので、変更に強い。
発見可能性: クライアントはドキュメントを熟読しなくても、APIのレスポンスを見るだけで「次に何ができるか」を発見できる。

5. 「RESTfulの呪縛」と現代のAPI設計

HATEOASは非常に強力な設計思想だ。しかし、現実のAPI設計で _links のような構造を頻繁に見かけるだろうか？答えは「ほぼNo」である。

なぜRESTの「理想」は普及しなかったのか。ここで「RESTfulの呪縛」という問題が見えてくる。

原理主義の呪縛と現実的課題

HATEOASを厳格に実装・運用しようとすると、いくつかの深刻な課題に直面する。

実装の複雑性: サーバーは、リソースの状態ごとに「次にできる操作」のリンクを動的に生成し、レスポンスに含めなければならない。これはサーバー側のロジックを非常に複雑にする。
パフォーマンスと冗長性: _links の情報は、多くのクライアントにとって冗長（余計なデータ）であり、通信量を増大させる。特にモバイルアプリ開発では、データ通信量は最小限に抑えたいという強い要求がある。
クライアント側のメリットの薄さ: 結局のところ、多くのアプリケーション（特にモバイルアプリ）では、サーバーとクライアントは一体で開発されることが多い。「サーバーが勝手にURIを変える」事態を想定するより、「最初から決めたURIをハードコーディングする」方が開発速度が速い。

HATEOASを完璧に実装した状態を「RESTfulレベル3」と呼ぶことがあるが、多くの開発者は「HATEOASは理想としては分かるが、コストに見合わない」と判断したのだ。

「なんちゃってREST」の呪縛

一方で、HATEOASを無視し、URIとHTTPメソッド（GET/POST/PUT/DELETE）の原則だけを採用したAPI、すなわち「HTTPを使ってJSONを返すAPI」が、一般的に「REST API」と呼ばれるようになった。

これに対し、原理主義的な立場からは「HATEOASを満たしていないAPIはRESTではない」という批判（「なんちゃってREST」）がしばしば起こる。

「RESTful（RESTの原則に忠実）でなければならない」という言葉が、半ば強迫観念のように開発現場で語られることがある。これが「RESTfulの呪縛」だ。

RESTの限界と新しい設計思想の台頭

「なんちゃってREST」が主流となる一方で、その設計にも限界が見えてきた。

N+1問題: 例えば、ユーザーリスト（/users）を取得し、その後で各ユーザーの所属部署（/departments/{id}）を取得する場合、リストの人数分(N回) + 最初の1回のAPIリクエストが必要になり、非常に非効率だ。
オーバーフェッチ (Over-fetching)
- 例: GET /users/123 でユーザー情報を取得する際、クライアント（例: アプリのヘッダー表示）は「名前」だけが欲しいのに、サーバーは住所、電話番号、生年月日など不要なデータまで全て返してしまうこと。
- 問題点: 不要なデータを転送するため、ネットワーク帯域を無駄にし、クライアント（特にモバイル）の処理速度やバッテリー消費に悪影響を与える。
アンダーフェッチ (Under-fetching)
- 例: クライアント（例: ユーザーのプロフィール画面）が「ユーザーの名前」と「そのユーザーが投稿した最新ブログ記事3件のタイトル」を一度に表示したいとする。
  1. まず GET /users/123 をリクエストし、ユーザーの「名前」を取得する。
  2. 次に GET /users/123/posts?limit=3 をリクエストし、そのユーザーの「最新ブログ記事3件」を取得する。
- 問題点: 1つの画面を表示するために、クライアントは複数回のAPIリクエスト（この場合は2回）を行う必要がある。これにより、サーバーとの往復（ラウンドトリップ）が増え、画面の表示完了までに時間がかかってしまう。

これらの問題を解決するため、RESTとは根本的に異なる設計思想が台頭してきた。

GraphQL: Facebookが開発した。クライアントが「欲しいデータ（の構造）」をクエリとしてサーバーに送信する。サーバーは要求された構造通りのデータを一度のリクエストで返す。N+1問題やオーバーフェッチを根本的に解決する。
gRPC: Googleが開発した。RPC（Remote Procedure Call）の一種で、HTTP/2をベースに高速な通信（シリアライズ）を行う。サーバー間の内部通信（マイクロサービス）などで絶大なパフォーマンスを発揮する。

これらは「RESTの代替」であり、RESTが苦手としていた領域（特にモバイルアプリやマイクロサービス）で急速に採用が広がっている。

考察：我々は何を設計すべきか

では、我々はRESTを捨てるべきなのだろうか？

筆者はそうは思わない。「RESTfulであること」自体が目的ではない。重要なのは、「RESTがなぜその原則（HATEOAS含む）を提唱したのか」という設計思想の背景を理解することだ。

HATEOASが目指した「クライアントとサーバーの疎結合」は、システムが長期的にスケールし、変更に強くあり続けるためには非常に重要な概念だ。

「RESTfulの呪縛」とは、この2つの側面を持つ。

HATEOASを無視した「なんちゃってREST」を盲目的に採用し、その限界（N+1問題など）に直面する呪縛。
HATEOASの理想を追求するあまり、現実的な開発速度やパフォーマンスを犠牲にしてしまう原理主義の呪縛。

現代のAPI設計者に求められるのは、「真のREST」の理想（HATEOASが目指した疎結合性）を理解し、その上で自分たちのプロジェクトの要件（開発速度、パフォーマンス、拡張性）を天秤にかけ、意識的な技術選択を行うことだ。

シンプルな操作が中心で、公開APIとして広く使われるなら、　HATEOASを無視した現実的なREST（いわゆるREST API）　は今でも最適解の一つだ。
モバイルアプリがフロントエンドで、柔軟なデータ取得が求められるなら、GraphQLが輝くだろう。
マイクロサービス間の内部通信で、速度が最優先されるなら、gRPCが適している。

RESTの原則、特にHATEOASは「銀の弾丸」ではなかった。しかし、それはAPI設計における「北極星」の一つとして、我々が進むべき方向性を今も示し続けている。

まとめ

この記事では、曖昧な理解で使われがちな「REST API」について、その土台となるHTTPの基本から、RESTの核となる設計原則（URIとHTTPメソッド）、そして多くの人が知らない「真の理想」であるHATEOASまでを掘り下げた。

APIとは「ソフトウェア同士の会話のルール」である。
REST APIとは、HTTPというWebの基本ルールに素直に従い、「何を（URI）」と「どうする（HTTPメソッド）」を分離して設計されたAPIである。
HATEOASは「レスポンスが次の操作を教える」というRESTの理想であり、クライアントとサーバーの疎結合を目指すものだ。
しかし、HATEOASは実装の複雑さなどから現実の多くでは採用されず、主流の「REST API」はHATEOASを省略したものとなっている。
この現実的なRESTの限界（N+1問題など）を背景に、GraphQLやgRPCといった新しい設計思想が台頭してきた。

最終的に重要なのは、流行の技術に飛びつくことでも、原理主義に固執することでもない。それぞれの設計思想が「何を解決しようとしたのか」を学び、直面する課題に対して最適な道具を選択する眼を持つことだ。

この記事が、あなたの「魔法の箱」だったAPIへの理解を深め、より良い設計への第一歩となれば幸いである。