JAX-RS（Java API for RESTful Web Services）

JAX-RS（Java API for RESTful Web Services）とは、RESTに基づいたウェブサービスを提供するJava EEのAPIです。この記事では、JAX-RSの使い方やアノテーションをご紹介します。

REST

REST (Representational State Transfer)とは、インターネット上のコンピュータシステム間の相互運用性を提供する方法である。

RESTful

RESTの原則に則していることを「RESTful」と呼ぶ。RESTの原則に即して実装されたWebサービスは「RESTful Webサービス」であり、RESTの原則に即したAPIは「RESTful API」である。

RESTfulシステムの場合、エンドポイントは「リソース」と呼ばれ、URIで示される。

実装

JAX-RSはAPI仕様であるため、実際に使用するには、JAX-RSを実装した下記ソフトウェアのいずれかが必要となる。

Apache CXF
JBoss RESTeasy
Jersey
Oracle WebLogic Server

プログラミング

システム内すべての社員を表すURIの例を次に示す。

/employees

個々の社員にアクセスするURIの例を次に示す。

/employees/empno

empno文字列は個々の社員を示す識別子であり、Employeeオブジェクトのempnoプロパティに対応する任意の値になる。

RESTfulインタフェースがネットワーク経由でクライアントに送るリソースのフォーマットとして、XMLやJSONが使われる。

<employee empno="5">
  <link rel="self" href="http://segakuin.com/employees/5"/>
  <ename>堀内まり菜</ename>
</employee>

Employeeのリストを得るため、リモートのクライアントは対象とするオブジェクトのグループのURIに対してHTTP GETを呼び出す。

GET /employees HTTP/1.1

サービスはシステム内の全Employeeを示すデータフォーマットを応答する。

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

<employees>
  <employee empno="5">
    <link rel="self" href="http://itref.fc2web.com/employees/5"/>
    <ename>堀内まり菜</ename>
  </employee>
  <employee empno="6">
    <link rel="self" href="http://itref.fc2web.com/employees/5"/>
    <ename>飯田來麗</ename>
  </employee>
</employees>

クライアントがURIでクエリパラメータを指定できるようにすることもできる。

GET /employees?startIndex=0&size=10 HTTP/1.1

PUTのHTTP定義では、PUTはサーバのリソースを作成または更新する際に使用できるとなっている。

PUTによってEmployeeを作成する場合、クライアントは作成対象となる新しいオブジェクトの表現を、オブジェクトを示すURIの場所に単に送信するだけで済む。

PUT /employees/25 HTTP/1.1

リクエストの結果として、サーバに新しいリソースが作成された場合、PUTでは「201 Created」のレスポンスコードを送るよう仕様により義務付けられている。

POSTメソッドを使って社員を作成する場合は、PUTのときよりも少し複雑になる。

POSTによってEmployeeを作成する場合、クライアントは作成対象となる新しいオブジェクトの表現をempnoを除外して、その表現の親URIに送信する。

POST /employees HTTP/1.1
Content-Type: application/xml

<employee>
  <ename>八木美樹</ename>
</employee>

サービスは、POSTメッセージを受け取り、XMLを処理して、データベースが生成する一意のempnoを使ってデータベース内に新しいオブジェクトを作成する。

新しいオブジェクトのempno等をクライアントに渡すため、追加の情報をHTTPレスポンスメッセージに付加する。

HTTP/1.1 201 Created
Content-Type: application/xml
Location: http://itref.fc2web.com/employees/30

<employee empno="30">
  <link rel="self" href="http://segakuin.com/employees/30"/>
  <ename>八木美樹</ename>
</employee>

アノテーション

JAX-RSはプレーン（普通の）Javaオブジェクトに対するアノテーションの適用に特化したフレームワークである。

JAX-RSには、特定のURIパターンとHTTPの操作をJavaクラスの個々のメソッドにバインドするためのアノテーションが用意されている。

JAX-RSは、クラスをウェブリソースにマッピングするためのアノテーションを提供している。JAX-RSのアノテーションを次に示す。

JAX-RSのアノテーション一覧
アノテーション	説明
@Consumes	リソースが受け付けるMIMEタイプを示す。
@Context	コンテキストの値をインジェクトする。
@CookieParam	クライアントによって設定されたHTTP Cookieから値を抽出する。
@DefaultValue	パラメータのデフォルト値を定義する。
@DELETE	JavaメソッドをDELETE HTTP操作にバインドする。
@FormParam	HTMLフォームパラメータ値をJavaメソッドにバインドする。
@GET	JavaメソッドをGET HTTP操作にバインドする。
@HeaderParam	HTTPリクエストヘッダから値を抽出する。
@MatrixParam	URIのマトリックスパラメータから値を抽出する。
@Path	相対的なパスを指定する。
@PathParam	URIテンプレートパラメータから値を抽出する。
@POST	JavaメソッドをPOST HTTP操作にバインドする。
@Produces	リソースがから返されるMIMEタイプを示す。
@PUT	JavaメソッドをPUT HTTP操作にバインドする。
@QueryParam	ポストされたフォームデータから値を抽出する。

@Consumes

@javax.ws.rs.Consumesは、リソースが受け付けるMIMEタイプを示すアノテーションである。

@Consumes(mediatype)

@Consumes(value=mediatype)

mediatype: リソースが受け付けるMIMEタイプを指定する。MIMEタイプの指定には、javax.ws.rs.core.MediaTypeクラスのフィールドを使用できる。

@DELETE

@javax.ws.rs.DELETEは、HTTPのDELETE要求に応答する処理のJavaメソッドに付けるアノテーションである。引数は無い。

@DELETE

@GET

@javax.ws.rs.GETは、HTTPのGET要求に応答する処理のJavaメソッドに付けるアノテーションである。引数は無い。

@GET

@Path

@javax.ws.rs.Pathは、リソースクラス又はクラスメソッドが要求を処理するURIパスを指定するアノテーションである。

構文

@Path(path)

@Path(value=path)

path

リソースクラス又はクラスメソッドの相対的なパスを指定する。ベースURIはアプリケーションパスである。

パスにはパスパラメータを含めることができる。たとえば社員リソースの一覧を取得するURLが"/emploees"だとすると、社員番号を指定して特定の社員リソースを取得するURLは"/emploees/{no}"となる。

サンプル

package com.fc2web.itref.examples.jaxrs;

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

@Path("/employees")
public class EmployeesResource {

  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public Employee getByEmployeeNo() {
      // 社員リソース一覧処理
  }

  @GET
  @Path("/{no}")
  @Produces(MediaType.APPLICATION_JSON)
  public Employee getByEmployeeNo(@PathParam("no") String no) {
      // 社員リソース取得処理
  }
}

@PathParam

URIテンプレートパラメータから値を抽出する。

@POST

@javax.ws.rs.POSTは、HTTPのPOST要求に応答する処理のJavaメソッドに付けるアノテーションである。引数は無い。

@POST

@POSTアノテーションのサンプルを次に示す。

@POST
@Consumes(MddiaType.TEXT_XML)
@Produces(MediaType.TEXT_XML)
public Employee() {
  // 処理
}

@Produces

@javax.ws.rs.Producesは、リソースから返されるMIMEタイプを示すアノテーションである。

@Produces(mediatype)

@Produces(value=mediatype)

mediatype: リソースから返されるMIMEタイプを指定する。MIMEタイプの指定には、javax.ws.rs.core.MediaTypeクラスのフィールドを使用できる。

@PUT

@javax.ws.rs.PUTは、HTTPのPUT要求に応答する処理のJavaメソッドに付けるアノテーションである。引数は無い。

@PUT