過去バージョン

JAX-RS とは

JAX-RS (Java API for RESTful Web Services) は、Java で REST API を構築するための標準仕様です。アノテーション主体の宣言的な書き方で、サーブレットを直接扱うよりも遙かにシンプルに REST エンドポイントを実装できます。

Java EE 8 までは javax.ws.rs.*、Jakarta EE 9 以降はjakarta.ws.rs.*に名前空間が変更されました。移行時はインポート文の置換が必要。

最小サンプル

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/hello")
public class HelloResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String sayHello() {
        return "Hello, JAX-RS!";
    }
}

これだけで GET /hello が動きます。サーブレット記述不要、web.xml も省略可能（Application クラスで @ApplicationPath を指定）。

主要アノテーション一覧

エンドポイント・HTTP メソッド

パラメータ注入

実装例: ユーザー API

import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.util.List;

@Path("/users")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class UserResource {

    @GET
    public List list(
        @QueryParam("page") @DefaultValue("1") int page,
        @QueryParam("size") @DefaultValue("20") int size
    ) {
        return userService.findAll(page, size);
    }

    @GET
    @Path("/{id}")
    public Response get(@PathParam("id") Long id) {
        User user = userService.findById(id);
        if (user == null) {
            return Response.status(404).build();
        }
        return Response.ok(user).build();
    }

    @POST
    public Response create(User user) {
        User created = userService.create(user);
        return Response.status(201).entity(created).build();
    }

    @PUT
    @Path("/{id}")
    public Response update(@PathParam("id") Long id, User user) {
        userService.update(id, user);
        return Response.noContent().build();
    }

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

JSON との連携

JAX-RS はPOJO ⇔ JSON の自動変換に対応しています。実装系（Jersey / RESTEasy）が Jackson か MOXy を内部で使用。

public class User {
    private Long id;
    private String name;
    private String email;
    // getter / setter ...
}

// このまま return すれば JSON で返る
@GET
@Path("/{id}")
@Produces(MediaType.APPLICATION_JSON)
public User get(@PathParam("id") Long id) {
    return userService.findById(id);
}

{ "id": 1, "name": "tarou", "email": "tarou@example.com" }

Application クラス

JAX-RS アプリのエントリポイント。@ApplicationPath でベース URL を指定。

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/api")
public class RestApplication extends Application {
    // クラスの明示登録は通常不要 (自動スキャン)
}

これによりhttps://host/コンテキスト/api/usersでアクセスできるようになります。

例外ハンドリング (ExceptionMapper)

import javax.ws.rs.core.Response;
import javax.ws.rs.ext.ExceptionMapper;
import javax.ws.rs.ext.Provider;

@Provider
public class NotFoundExceptionMapper implements ExceptionMapper {
    @Override
    public Response toResponse(NotFoundException ex) {
        return Response.status(404)
            .entity(Map.of("error", ex.getMessage()))
            .type(MediaType.APPLICATION_JSON)
            .build();
    }
}

主要な実装

Spring との関係

Spring MVC や Spring Boot は独自の REST フレームワークを持っていて、JAX-RS は使いません。アノテーションは似ていますが別物:

FAQ

Q: JAX-RS と Servlet どちらを使う？
A: REST API なら JAX-RS。セッション処理や任意の HTTP 処理なら Servlet。共存可能。

Q: javax と jakarta どちら？
A: 新規プロジェクトは jakarta。既存の Java EE 8 以前は javax のまま。混在不可。

Q: Spring Boot で JAX-RS は使える？
A: Jersey や CXF の Spring Boot Starter で使える。ただし通常は Spring MVC の方が情報が多く現実的。