この記事の要点

JAX-RS (Java API for RESTful Web Services) は Java で REST API を構築する標準仕様 JSR-339 (2.0) / JSR-370 (2.1) で標準化、現在は Jakarta EE 配下に移管 (Jakarta RESTful Web Services) 基本: @Path でエンドポイント、@GET/@POST/@PUT/@DELETE で HTTP メソッド対応 パラメータ: @PathParam (URL) / @QueryParam (クエリ) / @FormParam (フォーム) 主要実装: Jersey (リファレンス実装) / RESTEasy (JBoss) / Apache CXF JSON 連携: JAX-B + Jackson で POJO ⇔ JSON 自動変換

JAX-RS とは

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

バージョン	仕様	リリース
1.0	JSR-311	2008
1.1	JSR-311 (Java EE 6)	2009
2.0	JSR-339 (Java EE 7)	2013
2.1	JSR-370 (Java EE 8)	2017
3.0+	Jakarta RESTful Web Services (Jakarta EE 9+)	2020〜

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 メソッド

アノテーション	意味
@Path("...")	エンドポイントの URL パス
@GET	HTTP GET メソッド
@POST	HTTP POST メソッド
@PUT	HTTP PUT メソッド
@DELETE	HTTP DELETE メソッド
@HEAD / @OPTIONS	同名 HTTP メソッド
@Consumes("...")	受け付けるコンテンツタイプ
@Produces("...")	返すコンテンツタイプ

パラメータ注入

アノテーション	意味	例
@PathParam	URL パス変数	/users/{id} の id
@QueryParam	クエリ文字列	?page=2 の page
@FormParam	フォーム値	POST フォーム
@HeaderParam	HTTP ヘッダー	Authorization
@CookieParam	Cookie 値	JSESSIONID
@MatrixParam	マトリックスパラメータ	;color=red
@DefaultValue	パラメータ未指定時の既定値	@DefaultValue("10")

実装例: ユーザー 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<User> 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<NotFoundException> {
    @Override
    public Response toResponse(NotFoundException ex) {
        return Response.status(404)
            .entity(Map.of("error", ex.getMessage()))
            .type(MediaType.APPLICATION_JSON)
            .build();
    }
}

主要な実装

実装	提供元	特徴
Jersey	Eclipse Foundation	JAX-RS リファレンス実装。Java EE 標準
RESTEasy	JBoss / Red Hat	WildFly / Quarkus に標準採用
Apache CXF	Apache	SOAP / REST 両対応
Restlet	Restlet	独自フレームワーク（JAX-RS 互換）

Spring との関係

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

JAX-RS	Spring MVC
@Path("/users")	@RequestMapping("/users")
@GET	@GetMapping
@PathParam	@PathVariable
@QueryParam	@RequestParam
@Produces	produces= 属性

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 の方が情報が多く現実的。