REST APIとは｜HTTPメソッド・ステートレスと設計原則

編集

この記事の要点

REST（Representational State Transfer）はHTTP プロトコルを軸に据えた API 設計スタイル
リソースを URL で表現し、HTTP メソッド（GET / POST / PUT / DELETE）で操作するのが基本
ステートレス — サーバはセッション状態を保持せず、各リクエストは独立して完結する
Java EE / Jakarta EE では JAX-RS（Jersey / RESTEasy）が、Spring 系では Spring MVC / Spring WebFlux が定番実装
SOAP / RPC との違いは、軽量・キャッシュ可能・スケールしやすいこと。一方で厳密な仕様化は OpenAPI / Swagger 等が補う

REST とは

REST（Representational State Transfer）は、Roy Fielding が 2000 年の博士論文で提唱した分散システムのアーキテクチャスタイルです。Web を支える HTTP プロトコルを最大限活用する設計思想で、現在の Web API の事実上の標準になっています。「REST API」「RESTful」という言葉は、この設計原則に従った API を指します。

REST の 6 つの設計原則

原則	意味
クライアント / サーバ	関心の分離 — UI とデータを別レイヤーに
ステートレス	サーバはセッション状態を持たない — 各リクエストが完結
キャッシュ可能	レスポンスはキャッシュ可否を明示
統一インターフェース	リソース / 表現 / メッセージ / HATEOAS の統一
階層化システム	プロキシ / ゲートウェイ等を間に挟める
コードオンデマンド（任意）	JS などのコード配布 — 必須ではない

リソースと URI

REST ではすべてのものをリソースとして扱い、URI で識別します。動詞ではなく名詞を URI にするのが原則です。

NG（動詞ベース）	OK（リソースベース）
/getUser?id=1	GET /users/1
/createOrder	POST /orders
/updateProduct?id=10	PUT /products/10
/deleteUser?id=5	DELETE /users/5

HTTP メソッドと CRUD の対応

メソッド	用途	CRUD	冪等性	セーフ
GET	リソース取得	Read	○	○
POST	新規作成	Create	×	×
PUT	更新（全置換）	Update	○	×
PATCH	部分更新	Update	△	×
DELETE	削除	Delete	○	×

冪等: 同じ操作を何度繰り返しても結果が同じ。セーフ: サーバ状態を変更しない。これらの性質は分散システムのリトライやキャッシュ設計で重要です。

ステータスコード

コード	意味	典型シーン
200 OK	成功	GET / 一般成功
201 Created	作成成功	POST で新規作成完了
204 No Content	成功（本文なし）	DELETE 成功
301 / 302	リダイレクト	URL 変更
400 Bad Request	不正リクエスト	パラメータ不正
401 Unauthorized	未認証	トークンなし
403 Forbidden	権限なし	認証済だが権限不足
404 Not Found	存在しない	不正な ID
409 Conflict	競合	重複登録
500 Internal Server Error	サーバエラー	例外

JSON でのやり取り例

# 取得
GET /users/1 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "name": "山田太郎",
  "email": "yamada@example.com"
}

# 作成
POST /users HTTP/1.1
Content-Type: application/json

{ "name": "佐藤花子", "email": "sato@example.com" }

HTTP/1.1 201 Created
Location: /users/2

JAX-RS（Java EE / Jakarta EE）

Java EE / Jakarta EE における REST 実装は JAX-RS（Java API for RESTful Web Services）が標準仕様です。実装としては Jersey（リファレンス実装）や RESTEasy が代表的。

import jakarta.ws.rs.*;
import jakarta.ws.rs.core.*;

@Path("/users")
public class UserResource {

    @GET
    @Path("/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public User getUser(@PathParam("id") long id) {
        return userService.find(id);
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response create(User user) {
        User saved = userService.save(user);
        return Response.created(URI.create("/users/" + saved.getId()))
                       .entity(saved)
                       .build();
    }

    @PUT
    @Path("/{id}")
    public User update(@PathParam("id") long id, User user) {
        user.setId(id);
        return userService.update(user);
    }

    @DELETE
    @Path("/{id}")
    public Response delete(@PathParam("id") long id) {
        userService.delete(id);
        return Response.noContent().build();
    }
}

Spring Boot による実装

Spring 系では @RestController アノテーションで JAX-RS と同等のことができます。

@RestController
@RequestMapping("/users")
public class UserController {

    private final UserService userService;
    public UserController(UserService userService) { this.userService = userService; }

    @GetMapping("/{id}")
    public User getUser(@PathVariable long id) {
        return userService.find(id);
    }

    @PostMapping
    public ResponseEntity<User> create(@RequestBody User user) {
        User saved = userService.save(user);
        return ResponseEntity
                .created(URI.create("/users/" + saved.getId()))
                .body(saved);
    }

    @PutMapping("/{id}")
    public User update(@PathVariable long id, @RequestBody User user) {
        user.setId(id);
        return userService.update(user);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable long id) {
        userService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

SOAP / RPC との比較

項目	REST	SOAP	gRPC
プロトコル	HTTP	HTTP / SMTP 等	HTTP/2
フォーマット	JSON / XML	XML	Protocol Buffers（バイナリ）
仕様の厳密さ	緩い（OpenAPI で補う）	厳密（WSDL）	厳密（.proto）
ペイロード	軽い	重い	非常に軽い
ブラウザ親和性	高い	低い	低い（gRPC-Web 必要）
用途	公開 Web API	企業内システム	マイクロサービス間通信

REST API の設計ベストプラクティス

URI は名詞の複数形 （/users、/orders）
階層は2 階層程度に抑える（/users/1/orders はOK、/users/1/orders/2/items/3/tags/4 はやりすぎ）
クエリパラメータは絞り込み / ページング / ソートに（?status=active&page=2&sort=-createdAt）
バージョニング: /v1/users や Accept: application/vnd.api+json;version=1
エラーレスポンスはJSON で統一し、ステータスコード + 詳細メッセージを返す
認証は OAuth 2.0 / Bearer JWT が定番
レート制限は X-RateLimit-* ヘッダで明示

HATEOAS（応用）

真の REST（Roy Fielding が意図した “Level 3”）には HATEOAS（Hypermedia as the Engine of Application State）も含まれます。レスポンスに次に取れる操作をリンクとして埋め込み、クライアントは URL をハードコーディングせず辿るだけで API を使えるという考え方です。実際に厳密に実装するケースは少ないですが、参考としては重要。

{
  "id": 1,
  "name": "山田太郎",
  "_links": {
    "self":   { "href": "/users/1" },
    "orders": { "href": "/users/1/orders" },
    "delete": { "href": "/users/1", "method": "DELETE" }
  }
}

ページ一覧

その他