REST API

コントローラー の @RestController は、画面ではなくデータ（JSON など）を返します。このデータのやり取りでは、REST という設計様式が広く使われます。

1. REST の設計様式

URL とデータでやり取りする API の設計様式が REST（REpresentational State Transfer）です。データをリソースとして URL で表し、そのリソースへの操作を HTTP メソッドで表します。

1-1. リソースと URL

API がやり取りするデータを リソース と呼びます。本・利用者・注文のように、アプリケーションが扱う対象がリソースです。REST では、リソースのそれぞれに URL を割り当てて識別します。

リソースには、全体を指す URL と、その中の 1 件を指す URL があります。

URL	指すリソース
/api/books	本の一覧（全体）
/api/books/1	id が 1 の本（1 件）

一覧の URL の末尾に id を付けると、その id の 1 件を指します。

1-2. 操作と HTTP メソッド

同じリソースに対する取得・作成・更新・削除を、URL ではなく HTTP メソッドで区別します。

メソッド	操作
GET	取得
POST	作成
PUT	更新
DELETE	削除

/api/books/1 という同じ URL でも、GET なら取得、DELETE なら削除を表します。リソースを URL で、操作を HTTP メソッドで表し、JSON でやり取りする — この様式に沿った API を REST API と呼びます。

2. 公開 REST API での確認

JSONPlaceholder は、テスト用に公開されている REST API です。https://jsonplaceholder.typicode.com に続けて URL を開くと、REST の設計様式 を実際の応答で確認できます。

2-1. URL とリソースの対応

リソースと URL の対応は、応答の形に現れます。/todos/1 は、id が 1 の todo を 1 件のオブジェクトで返します。

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

末尾の id を外した /todos は、todo の全件をオブジェクトの配列で返します。1 件のリソースはオブジェクト、一覧は配列という対応です。

[
  { "userId": 1, "id": 1, "title": "delectus aut autem", "completed": false },
  { "userId": 1, "id": 2, "title": "quis ut nam facilis et officia qui", "completed": false }
]

2-2. ブラウザーが送るメソッド

ブラウザーのアドレス欄で URL を開く操作は、HTTP メソッドの GET にあたります。URL とリソースの対応 で開いた URL がすべて取得だったのは、このためです。操作と HTTP メソッド の作成・更新・削除（POST・PUT・DELETE）は、アドレス欄に URL を入力する方法では送れません。

JSONPlaceholder が示すこの仕組み — リソースを URL で表し、GET で取得し、JSON を返す — が REST API です。@RestController は、これと同じ REST API を自分で実装するためのものです。