過去バージョン

REST とは

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

REST の 6 つの設計原則

リソースと URI

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

HTTP メソッドと CRUD の対応

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

ステータスコード

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 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" }
  }
}

関連

• JAX-RS — Jakarta EE の REST API 仕様
• Jersey / RESTEasy — JAX-RS の代表実装
• Spring MVC / @RestController — Spring Boot での REST 実装
• JSON — REST API の主流データフォーマット
• OpenAPI / Swagger — REST API のスキーマ定義
• gRPC — Protocol Buffers ベースの RPC
• GraphQL — リソース指向に対するクエリベースの代替