Copyright 2015 NTT DATA INTRAMART CORPORATION 1 Top
目 次 intra-mart Accel Platform Web API Maker プログラミングガイド 第 2 版 2015-12-01 1. 改 訂 情 報 2. はじめに 2.1. 本 書 の 目 的 2.2. 対 象 読 者 2.3. 注 意 事 項 2.4. サンプルコードについて 2.5. 本 書 の 構 成 3. Web API Maker 概 要 3.1. Web API Maker とは 3.2. Web API Maker の 機 能 3.3. Web API Maker のモジュール 構 成 4. Web API Maker を 利 用 したAPIの 作 成 方 法 4.1. 全 体 の 作 業 の 流 れ 4.2. 前 提 条 件 4.3. ファクトリクラスの 作 成 4.4. サービスクラスの 作 成 4.4.1. サービスクラスの 作 成 < 基 本 > 4.4.2. @Beanについて 4.4.3. セキュアトークンによるトークンチェックを 行 う 4.4.4. 認 可 チェックを 行 う 4.4.5. 返 却 するステータスコードを 指 定 する 4.4.6. 手 動 レスポンスを 返 却 する 4.4.7. APIドキュメントを 登 録 する 4.5. 引 数 戻 り 値 に 指 定 可 能 な 型 4.6. パッケージの 登 録 5. 作 成 したAPIの 利 用 について 5.1. 利 用 方 法 5.2. セッション 管 理 5.3. API 仕 様 を 参 照 する 5.4. Web 上 からAPI 仕 様 を 参 照 し 実 行 する 6. サンプルについて 6.1. サンプルアプリケーションの 仕 様 6.2. サンプルの 資 材 一 覧 2
改 訂 情 報 intra-mart Accel Platform Web API Maker プログラミングガイド 第 2 版 2015-12-01 変 更 年 月 日 変 更 内 容 2015-08-01 初 版 2015-12-01 第 2 版 下 記 を 追 加 変 更 しました Web API Maker を 利 用 したAPIの 作 成 方 法 の サービスクラスの 作 成 < 基 本 > にBasic 認 証 に 関 する 説 明 を 追 記 しました 3
はじめに intra-mart Accel Platform Web API Maker プログラミングガイド 第 2 版 2015-12-01 本 書 の 目 的 本 書 では intra-mart Accel Platform で 提 供 する Web API Maker を 用 いたプログラミング 方 法 や 注 意 点 等 について 説 明 します 説 明 範 囲 は 以 下 の 通 りです Web API Maker の 概 要 基 本 仕 様 Web API Maker を 利 用 したAPIの 作 成 方 法 Web API Maker で 作 成 したAPI 利 用 時 の 注 意 点 対 象 読 者 本 書 は 以 下 の 条 件 を 満 たす 人 を 対 象 としています Web API Maker を 用 いて intra-mart Accel Platform 上 で Web API を 提 供 したい 開 発 者 次 の 内 容 を 理 解 していることが 必 須 となります Javaを 理 解 している 注 意 事 項 1. Web API Maker を 利 用 するにあたり いくつかの 制 限 事 項 が 存 在 します 制 限 事 項 についての 詳 細 は リリースノート 制 限 事 項 を 参 照 してくださ い サンプルコードについて 本 書 に 掲 載 されているサンプルコードは 可 読 性 を 重 視 しており 性 能 面 や 保 守 性 といった 観 点 において 必 ずしも 適 切 な 実 装 ではありません サンプルコードを 参 考 に 開 発 する 場 合 は 上 記 について 十 分 に 注 意 してください 本 書 の 構 成 本 書 は 以 下 のような 内 容 で 構 成 されています Web API Maker 概 要 Web API Maker を 利 用 したAPIの 作 成 方 法 作 成 したAPIの 利 用 について サンプルについて 4
Web API Maker 概 要 Web API Maker とは Web API とは HTTPベースでデータをやりとりするための API です Web API Maker を 利 用 することで intra-mart Accel Platform 上 でWebサービスをシンプルに 実 現 することができます Web API Maker の 機 能 Web API Maker では 以 下 の 機 能 を 提 供 します Java 言 語 のクラス メソッドに 対 してアノテーションを 付 与 することにより 対 象 のクラスをWebサービス プロバイダとして 利 用 可 能 とする 機 能 上 記 のWebサービス プロバイダにWebサービスとしての 仕 様 をJSON 形 式 で 出 力 する 機 能 Web API Maker のモジュール 構 成 Web API Maker は 以 下 のモジュール 構 成 になります Web API Maker Web API Maker OAuth 認 証 モジュール Web API Maker でOAuth2による 認 証 を 行 う 場 合 に 必 要 となります 5
Web API Maker を 利 用 したAPIの 作 成 方 法 項 目 全 体 の 作 業 の 流 れ 前 提 条 件 ファクトリクラスの 作 成 サービスクラスの 作 成 サービスクラスの 作 成 < 基 本 > @Beanについて セキュアトークンによるトークンチェックを 行 う 認 可 チェックを 行 う 返 却 するステータスコードを 指 定 する 手 動 レスポンスを 返 却 する APIドキュメントを 登 録 する 引 数 戻 り 値 に 指 定 可 能 な 型 パッケージの 登 録 全 体 の 作 業 の 流 れ Web API Maker を 利 用 したAPIの 作 成 は 以 下 の 流 れで 行 います ファクトリクラスの 作 成 ファクトリクラスおよびサービスクラスのインスタンスを 生 成 するクラスを 作 成 します サービスクラスの 作 成 Webサービス プロバイダとしてのインタフェースの 決 定 任 意 の 処 理 を 実 装 します パッケージの 登 録 作 成 したファクトリクラスを 列 挙 します 前 提 条 件 Web API Maker を 利 用 しAPIを 作 成 するには 以 下 の 前 提 条 件 があります 提 供 するAPIのファクトリクラス サービスクラス サービスクラスのインタフェースに 含 まれるモデルはすべてpublicである 必 要 があります モデルを 利 用 した 場 合 に 有 効 となるプロパティは 対 となる getter, setter があるメンバのみです モデルは 引 数 無 しのコンストラクタを 提 供 する 必 要 があります データの 受 け 渡 しにXMLを 利 用 する 場 合 でインタフェースにモデルが 含 まれる 場 合 そのモデルクラスに@XmlRootElementアノテーションを 付 与 する 必 要 があります モデルのプロパティにMapがあり そのvalueの 型 がObjectである 場 合 は 値 に 格 納 される 値 が 形 式 毎 に 異 なる 可 能 性 があります データの 受 け 渡 しにJSONを 利 用 する 場 合 は Boolean, BigDecimal, String になります データの 受 け 渡 しにXMLを 利 用 する 場 合 は String のみになります 注 意 データの 受 け 渡 しに 関 しては 利 用 方 法 を 参 照 してください ファクトリクラスの 作 成 ファクトリクラス および サービスクラスのインスタンス 生 成 を 行 うファクトリクラスを 作 成 します ファクトリクラスでは 以 下 の サービスプロバイダアノテーション を 利 用 します Web API Maker ではサービスクラスに 付 与 されているアノテーションを 元 にWebサービス プロバイダとしての 仕 様 が 決 定 します 仕 様 の 決 定 はファクトリクラスの @ProvideService が 付 与 されているメソッドの 戻 り 値 のクラスに 付 与 されているアノテーションにて 決 定 します サービスプロバイダアノテーションの 種 類 6
@WebAPIMaker Web API Makder 機 能 を 利 用 することを 意 味 するアノテーションです ファクトリクラスのクラスに 付 与 します @ProvideFactory @ProvideService ファクトリクラスのインスタンスの 取 得 元 であることを 意 味 するアノテーションです ファクトリクラスのファクトリインスタンス 取 得 メソッドに 付 与 します 付 与 されたメソッドは 一 度 のみ 実 行 され ファクトリクラスのインスタンスは Web API Maker 内 部 でキャッシュさ れます サービスクラスのインスタンスの 取 得 元 であることを 意 味 するアノテーションです ファクトリクラスのサービスインスタンス 取 得 メソッドに 付 与 します このアノテーションを 付 与 されたメソッドは 提 供 するWebサービス プロバイダを 実 行 する 度 に 呼 び 出 されます メソッドを 作 りこむことでサービスクラスのインスタンスのライフサイクルを 管 理 することが 可 能 です ファクトリクラスの 実 装 例 は 以 下 の 通 りです package jp.co.intra_mart.sample.web_api_maker.pet_shop.service; import jp.co.intra_mart.foundation.web_api_maker.annotation.providefactory; import jp.co.intra_mart.foundation.web_api_maker.annotation.provideservice; import jp.co.intra_mart.foundation.web_api_maker.annotation.webapimaker; @WebAPIMaker public class PetServiceFactory { @ProvideFactory public static PetServiceFactory getfactory() { return new PetServiceFactory(); @ProvideService public PetService getservice() { return new PetService(); サービスクラスの 作 成 サービスクラスでは アノテーションによるWebサービス プロバイダとしてのインタフェースの 決 定 任 意 の 処 理 を 実 装 します 提 供 したいWebサービスをメソッドとして 記 述 します ここではサービスクラスの 作 成 方 法 と 各 アノテーションに 関 して 説 明 します サービスクラスの 作 成 < 基 本 > サービスクラスは 以 下 の 手 順 で 作 成 します 1. 認 証 方 式 を 決 定 して 対 応 する 認 証 アノテーション をサービスクラスに 付 与 します 認 証 アノテーションは API 実 行 時 の 認 証 方 式 を 指 定 するアノテーション 群 です 認 証 アノテーション 概 要 @IMAuthentication @BasicAuthentication @OAuth Cookieを 利 用 したアクセスを 行 う 場 合 に 付 与 するアノテーション 特 別 な 認 証 処 理 を 行 わず Cookieに 紐 づくセッションの 認 証 状 態 でアクセスします Basic 認 証 による 認 証 行 う 場 合 に 付 与 するアノテーション /basic + 後 述 の @Path のvalueの 値 がBasic 認 証 を 利 用 したエンドポイントとなります /basic の 文 字 列 はアノテーションの 属 性 で 変 更 する 事 が 可 能 です OAuth2による 認 証 を 行 う 場 合 に 付 与 するアノテーション /oauth + 後 述 の @Path のvalue 値 がOAuth 認 証 を 利 用 したエンドポイントとなります /oauth の 文 字 列 はアノテーションの 属 性 で 変 更 する 事 が 可 能 です 別 途 scopeの 定 義 を 行 う 必 要 があります 7
コラム intra-mart Accel Platform のOAuth 認 証 については OAuth 認 証 モジュール 仕 様 書 を 参 照 してください OAuthのscope 定 義 に ついては 設 定 ファイルリファレンス - クライアントのアクセス 範 囲 設 定 を 参 照 してください コラム Basic 認 証 では 以 下 のような 環 境 で 認 証 時 にテナントを 指 定 することができます バーチャルテナントによる 複 数 テナントを 利 用 していて リクエスト 情 報 を 利 用 したテナント 自 動 解 決 機 能 を 利 用 していない 環 境 上 記 環 境 では 認 証 時 にユーザコードとして テナントID\ユーザコード を 指 定 すると 指 定 したテナントに 対 して 認 証 を 行 います ユーザコードとしてユーザコードのみを 指 定 すると デフォルトテナントに 対 して 認 証 を 行 います 2. 各 メソッドにアクセスするURLを 決 め パスアノテーション をメソッドに 付 与 します パスアノテーションはリクエストを 送 る 際 にURLにバインドするパスを 指 定 するアノテーションです パスアノテーション 概 要 @Path /xxx 形 式 でパスを 指 定 します パスに {xxx 形 式 を 含 めることでxxxの 値 をパラメータとして 利 用 可 能 で す 3. 受 け 付 ける HTTP メソッドに 対 応 する HTTPメソッドアノテーション をメソッドに 付 与 します パスアノテーションを 付 与 したメソッドにて 許 可 するHTTPメソッドを 指 定 します 指 定 するアノテーションによってメソッドで 利 用 可 能 な 引 数 の 型 が 異 なります 詳 しくは 後 述 の 引 数 戻 り 値 に 指 定 可 能 な 型 を 参 照 してください パスアノテーションを 付 与 したメソッドには1つ 以 上 付 与 する 必 要 があります HTTPメソッドアノテーション 概 要 @GET @PUT @POST @DELETE GETメソッドを 受 け 付 けます このアノテーションを 付 与 した 場 合 エンティティボディを 利 用 するパラメータは 利 用 できませ ん PUTメソッドを 受 け 付 けます POSTメソッドを 受 け 付 けます DELETEメソッドを 受 け 付 けます このアノテーションを 付 与 した 場 合 エンティティボディを 利 用 するパラメータは 利 用 できませ ん 4. メソッドに 引 数 がある 場 合 値 をどのように 受 け 取 るかに 対 応 する パラメータアノテーション をメソッドに 付 与 します HTTPメソッドやパラメータアノテーションごとに 受 け 取 り 可 能 な 型 が 異 なります 詳 しくは 後 述 の 引 数 戻 り 値 に 指 定 可 能 な 型 を 参 照 してください パラメータアノテーション 概 要 @Parameter @Header @Variable @Body @Bean クエリパラメータまたはフォームパラメータ(マルチパート 含 む)として 引 数 情 報 を 受 け 付 けます パラメータ 名 を 指 定 する 必 要 があります メソッド 内 で 同 一 のパラメータ 名 を 利 用 できません リクエストヘッダの 値 を 引 数 情 報 として 受 け 付 けます パラメータ 名 を 指 定 する 必 要 があります メソッド 内 で 同 一 のパラメータ 名 を 利 用 できません パラメータの 値 を 引 数 情 報 として 受 け 付 けます @Path アノテーションに 指 定 したパス 値 にパラメータの 形 式 を 含 める 必 要 があります パラメータ 名 を 指 定 する 必 要 があります メソッド 内 で 同 一 のパラメータ 名 を 利 用 できません エンティティボディの 内 容 を 引 数 情 報 として 受 け 付 けます 上 記 のパラメータを 一 括 して1つのBeanとして 受 け 取 るアノテーション @Beanが 指 定 された 型 が 持 つメンバーにパラメータアノテーションが 付 与 されている 場 合 それらをバ インドした 状 態 のBeanが 利 用 できます 詳 細 は 後 述 の @Beanについて を 参 照 してください 8
アノテーションなし intra-mart Accel Platform Web API Maker プログラミングガイド 第 2 版 2015-12-01 各 引 数 にnullまたは 初 期 値 (プリミティブbooleanだとfalse)が 必 ずわたるようになります HttpServletRequestおよびHttpServletResponseを 指 定 した 場 合 リクエスト 中 のそれらのインスタン スがバインドされるため 主 にリクエストやレスポンスを 直 接 参 照 したい 場 合 に 利 用 します @Required 実 行 するメソッドに 渡 す 引 数 の 値 が 必 須 であることを 表 すアノテーションです 上 記 のアノテーションと 組 み 合 わせて 利 用 します サービスクラスの 実 装 例 は 以 下 の 通 りです package jp.co.intra_mart.sample.web_api_maker.pet_shop.service; import jp.co.intra_mart.foundation.web_api_maker.annotation.body; import jp.co.intra_mart.foundation.web_api_maker.annotation.delete; import jp.co.intra_mart.foundation.web_api_maker.annotation.get; import jp.co.intra_mart.foundation.web_api_maker.annotation.imauthentication; import jp.co.intra_mart.foundation.web_api_maker.annotation.post; import jp.co.intra_mart.foundation.web_api_maker.annotation.put; import jp.co.intra_mart.foundation.web_api_maker.annotation.path; import jp.co.intra_mart.foundation.web_api_maker.annotation.required; import jp.co.intra_mart.foundation.web_api_maker.annotation.variable; import jp.co.intra_mart.sample.web_api_maker.pet_shop.model.pet; @IMAuthentication public class PetService { @Path("/sample/pet-shop/pet/{id") @DELETE public void delete(@required @Variable(name = "id") final int id) throws NotFoundException { for (final Pet p : ConstantData.PETS) { if (p.getid() == id) { // delete return; @Path("/sample/pet-shop/pet/{id") @GET public Pet get(@required @Variable(name = "id") final int id) throws NotFoundException { for (final Pet pet : ConstantData.PETS) { if (pet.getid() == id) { return pet; @Path("/sample/pet-shop/pets") @POST public void register(@required @Body final Pet pet) { // register @Path("/sample/pet-shop/pet/{id") @PUT public void update(@required @Variable(name = "id") final int id, @Required @Body final Pet pet) throws NotFoundException { for (final Pet p : ConstantData.PETS) { if (p.getid() == id) { // update return; 9
注 意 intra-mart Accel Platform Web API Maker プログラミングガイド 第 2 版 2015-12-01 サービスクラスはインタフェースでもクラスでも 動 作 します @Beanについて @Beanを 利 用 することで 複 数 のパラメータを1つのBeanでまとめて 受 け 取 ることができます @Beanを 付 与 された 引 数 のクラスが 持 つメンバーのSetterメソッドに 付 与 されているアノテーションによりメンバーの 値 をリクエストにバインドします @Beanを 付 与 するクラスは 以 下 を 満 たす 必 要 があります publicなクラスである publicな 引 数 なしのコンストラクタが 存 在 する @Beanに 付 与 されたメソッドが 以 下 を 満 たす 場 合 1つのメンバとして 扱 われます 対 となるgetter, setterが 存 在 する メソッド 名 がgetXxxx(booleanの 場 合 に 限 りisXxxx)である 引 数 なしでかつ 戻 り 値 を 持 つメソッドが 存 在 する メソッド 名 がsetXxxxである 引 数 が1つであり 戻 り 値 が 無 いメソッドが 存 在 する getterの 引 数 の 型 戻 り 値 の 型 が 同 一 である staticではない publicである setterメソッドにパラメータアノテーションが 付 与 されている(ただし @Beanは 利 用 不 可 です) 実 装 例 は 以 下 の 通 りです 10
package jp.co.intra_mart.sample.web_api_maker.pet_shop.service; import jp.co.intra_mart.foundation.web_api_maker.annotation.bean; import jp.co.intra_mart.foundation.web_api_maker.annotation.body; import jp.co.intra_mart.foundation.web_api_maker.annotation.imauthentication; import jp.co.intra_mart.foundation.web_api_maker.annotation.put; import jp.co.intra_mart.foundation.web_api_maker.annotation.path; import jp.co.intra_mart.foundation.web_api_maker.annotation.required; import jp.co.intra_mart.foundation.web_api_maker.annotation.variable; import jp.co.intra_mart.sample.web_api_maker.pet_shop.meta.petshop; import jp.co.intra_mart.sample.web_api_maker.pet_shop.meta.pettag; import jp.co.intra_mart.sample.web_api_maker.pet_shop.model.pet; @IMAuthentication public class PetService { public static class BeanClass { public int id; public Pet pet; public int getid() { return id; public Pet getpet() { return pet; @Required @Variable(name = "id") public void setid(final int id) { this.id = id; @Required @Body public void setpet(final Pet pet) { this.pet = pet; @Path("/sample/pet-shop/pet/{id") @PUT public void update(@bean final BeanClass bean) throws NotFoundException { for (final Pet p : ConstantData.PETS) { if (p.getid() == bean.id) { // update return; セキュアトークンによるトークンチェックを 行 う intra-mart Accel Platform ではセキュアトークンを 利 用 することにより 生 成 されるトークンに 対 してサーバ 側 でトークンチェック 処 理 を 行 い CSRF 対 策 を 行 うことができます セキュアチェックアノテーションを 利 用 することで Web API 実 行 前 にセキュアトークンによるトークンチェックを 行 うかどうかを 指 定 することができます セキュアチェックアノテーション 概 要 11
@Secured intra-mart Accel Platform Web API Maker プログラミングガイド 第 2 版 2015-12-01 Web API 実 行 前 にセキュアトークンによるトークンチェックを 行 います このアノテーションはメソッドに 付 与 可 能 です トークンの 発 行 は SecureTokenManager で 行 います トークンの 発 行 とWeb APIへのリクエストは 同 一 のセッション 内 で 行 う 必 要 があります OAuthを 利 用 したWeb APIの 場 合 このアノテーションは 無 視 されます このアノテーションを 付 与 されたWeb APIを 実 行 する 場 合 クライアントはリクエストヘッダ X-Intramart- Secure-Token にトークンを 含 める 必 要 があります トークンチェックにより トークンが 妥 当 ではない 場 合 HTTPステータスコード403が 返 却 されます 実 装 例 は 以 下 の 通 りです 12
package jp.co.intra_mart.sample.web_api_maker.pet_shop.service; import jp.co.intra_mart.foundation.web_api_maker.annotation.body; import jp.co.intra_mart.foundation.web_api_maker.annotation.delete; import jp.co.intra_mart.foundation.web_api_maker.annotation.get; import jp.co.intra_mart.foundation.web_api_maker.annotation.imauthentication; import jp.co.intra_mart.foundation.web_api_maker.annotation.post; import jp.co.intra_mart.foundation.web_api_maker.annotation.put; import jp.co.intra_mart.foundation.web_api_maker.annotation.path; import jp.co.intra_mart.foundation.web_api_maker.annotation.required; import jp.co.intra_mart.foundation.web_api_maker.annotation.secured; import jp.co.intra_mart.foundation.web_api_maker.annotation.variable; import jp.co.intra_mart.sample.web_api_maker.pet_shop.model.pet; @IMAuthentication public class PetService { @Path("/sample/pet-shop/pet/{id") @DELETE @Secured public void delete(@required @Variable(name = "id") final int id) throws NotFoundException { for (final Pet p : ConstantData.PETS) { if (p.getid() == id) { // delete return; @Path("/sample/pet-shop/pet/{id") @GET @Secured public Pet get(@required @Variable(name = "id") final int id) throws NotFoundException { for (final Pet pet : ConstantData.PETS) { if (pet.getid() == id) { return pet; @Path("/sample/pet-shop/pets") @POST @Secured public void register(@required @Body final Pet pet) { // register @Path("/sample/pet-shop/pet/{id") @PUT @Secured public void update(@required @Variable(name = "id") final int id, @Required @Body final Pet pet) throws NotFoundException { for (final Pet p : ConstantData.PETS) { if (p.getid() == id) { // update return; 認 可 チェックを 行 う 認 可 アノテーションを 利 用 することで Web API 実 行 前 にIM-Authzによる 認 可 チェックを 行 うことができます 13
認 可 アノテーション 概 要 @Authz Web API 実 行 前 にIM-Authzによって 指 定 した 認 可 リソース(または 認 可 マッパー)にて 認 可 判 断 を 行 いま す 予 め 認 可 リソースを 準 備 する 必 要 があります このアノテーションはクラスまたはメソッドに 付 与 可 能 です クラスに 付 与 した 場 合 すべてのメソッドに 対 して 認 可 が 有 効 になります クラス メソッド 両 方 に 付 与 されて いる 場 合 メソッドの 指 定 が 優 先 されます 認 可 によりWeb APIの 実 行 する 権 限 がないと 判 断 された 場 合 HTTPステータスコード401または403が 返 却 されます 未 認 証 の 場 合 に401 認 証 された 状 態 で 権 限 がない 場 合 は403となります 実 装 例 は 以 下 の 通 りです 14
package jp.co.intra_mart.sample.web_api_maker.pet_shop.service; import jp.co.intra_mart.foundation.authz.annotation.authz; import jp.co.intra_mart.foundation.web_api_maker.annotation.body; import jp.co.intra_mart.foundation.web_api_maker.annotation.delete; import jp.co.intra_mart.foundation.web_api_maker.annotation.get; import jp.co.intra_mart.foundation.web_api_maker.annotation.imauthentication; import jp.co.intra_mart.foundation.web_api_maker.annotation.post; import jp.co.intra_mart.foundation.web_api_maker.annotation.put; import jp.co.intra_mart.foundation.web_api_maker.annotation.path; import jp.co.intra_mart.foundation.web_api_maker.annotation.required; import jp.co.intra_mart.foundation.web_api_maker.annotation.variable; import jp.co.intra_mart.sample.web_api_maker.pet_shop.model.pet; @IMAuthentication @Authz(uri = "service://sample/pet-shop", action = "execute") public class PetService { @Path("/sample/pet-shop/pet/{id") @DELETE public void delete(@required @Variable(name = "id") final int id) throws NotFoundException { for (final Pet p : ConstantData.PETS) { if (p.getid() == id) { // delete return; @Path("/sample/pet-shop/pet/{id") @GET public Pet get(@required @Variable(name = "id") final int id) throws NotFoundException { for (final Pet pet : ConstantData.PETS) { if (pet.getid() == id) { return pet; @Path("/sample/pet-shop/pets") @POST public void register(@required @Body final Pet pet) { // register @Path("/sample/pet-shop/pet/{id") @PUT public void update(@required @Variable(name = "id") final int id, @Required @Body final Pet pet) throws NotFoundException { for (final Pet p : ConstantData.PETS) { if (p.getid() == id) { // update return; コラム 認 可 については 認 可 仕 様 書 を 参 照 してください 返 却 するステータスコードを 指 定 する Web API Maker では 処 理 が 正 常 に 終 了 した 場 合 はステータスコード 200 が 返 却 され 例 外 が 投 げられ 処 理 が 終 了 した 場 合 はステータスコード 500 が 返 却 されます 15
@Response を 付 与 することで HTTPのレスポンスでクライアントに 返 却 するステータスコードを 指 定 することができます HTTPレスポンスアノテーション 概 要 @Response このアノテーションはサービスクラスのメソッド またはExceptionクラスに 付 与 が 可 能 です このアノテーションを 付 与 する 事 により Web API Maker が 指 定 のレスポンスを 返 却 します ただし セキュアチェック 認 証 認 可 チェック 等 によるエラー 発 生 時 はその 限 りではありませ ん 以 下 は Exception クラスに 付 与 した 例 になります package jp.co.intra_mart.sample.web_api_maker.pet_shop.service; import jp.co.intra_mart.foundation.web_api_maker.annotation.response; @Response(code = 404) public class NotFoundException extends Exception { public NotFoundException(final String message) { super(message); 注 意 @Responseを 指 定 しない 場 合 にレスポンスされる HTTP ステータスについては 利 用 方 法 を 参 照 してください 手 動 レスポンスを 返 却 する Web API Maker では HTTPのレスポンスとして エラーの 有 無 とAPIの 戻 り 値 情 報 を 書 き 込 みます @PreventWritingResponse を 付 与 する 事 により Web API Maker 側 からレスポンスの 書 き 込 みを 行 わないようになります 手 動 レスポンスアノテーション 概 要 @PreventWritingResponse このアノテーションはメソッドに 付 与 が 可 能 です このアノテーションを 付 与 する 事 により Web API Maker 側 からレスポンスの 書 き 込 みを 行 わないようになり ます ただし セキュアチェック 認 証 認 可 チェック 等 によるエラー 発 生 時 は 書 き 込 みが 発 生 します APIの 引 数 に HttpServletResponse(パラメータアノテーション 無 し)を 指 定 する 事 で HttpServletResponse を 取 得 可 能 なので そのレスポンスを 利 用 して 任 意 のレスポンスを 返 す 事 が 可 能 と なります 実 装 例 は 以 下 の 通 りです 16
package jp.co.intra_mart.sample.web_api_maker.pet_shop.service; import java.io.ioexception; import javax.servlet.http.httpservletresponse; import jp.co.intra_mart.foundation.web_api_maker.annotation.get; import jp.co.intra_mart.foundation.web_api_maker.annotation.imauthentication; import jp.co.intra_mart.foundation.web_api_maker.annotation.path; import jp.co.intra_mart.foundation.web_api_maker.annotation.preventwritingresponse; import jp.co.intra_mart.sample.web_api_maker.pet_shop.meta.petshop; @IMAuthentication public class PetService { @Path("/sample/pet-shop/redirect") @GET @PreventWritingResponse public void redirect(final HttpServletResponse response) throws IOException { response.sendredirect("/sample/pet-shop"); APIドキュメントを 登 録 する APIドキュメント(Swagger specification) 出 力 用 の APIドキュメントアノテーション を 利 用 することで APIドキュメントの 出 力 を 行 うことができます APIドキュメントアノテーションは 主 にAPIドキュメントでの 各 メソッドのカテゴライズに 利 用 します APIドキュメントを 出 力 するためには アノテーション 自 体 を 作 成 し 付 与 する 必 要 があります 各 項 目 にメッセージコードを 指 定 することで 国 際 化 対 応 ができます サービスクラスに 付 与 するアノテーションの 実 装 例 は 以 下 になります package jp.co.intra_mart.sample.web_api_maker.pet_shop.meta; @Retention(RetentionPolicy.RUNTIME) @Tag(name = "tag", description = "CAP.Z.IWP.WEBAPIMAKER.SAMPLE.PETSHOP.CATEGORY.DESCRIPTION") //メッセージコードを 指 定 することで 国 際 化 できます public @interface PetTag { サービスクラスのメソッドに 付 与 するアノテーションの 実 装 例 は 以 下 になります package jp.co.intra_mart.sample.web_api_maker.pet_shop.meta; @Retention(RetentionPolicy.RUNTIME) @Category(value = "petshop", name = "ペットショップ", description = "ペットショップAPIです", version = "1.0.0") public @interface PetShop { 作 成 したアノテーションの 利 用 し APIドキュメントを 登 録 する 例 は 以 下 になります 17
package jp.co.intra_mart.sample.web_api_maker.pet_shop.service; import jp.co.intra_mart.foundation.web_api_maker.annotation.body; import jp.co.intra_mart.foundation.web_api_maker.annotation.delete; import jp.co.intra_mart.foundation.web_api_maker.annotation.get; import jp.co.intra_mart.foundation.web_api_maker.annotation.imauthentication; import jp.co.intra_mart.foundation.web_api_maker.annotation.post; import jp.co.intra_mart.foundation.web_api_maker.annotation.put; import jp.co.intra_mart.foundation.web_api_maker.annotation.path; import jp.co.intra_mart.foundation.web_api_maker.annotation.required; import jp.co.intra_mart.foundation.web_api_maker.annotation.variable; import jp.co.intra_mart.sample.web_api_maker.pet_shop.meta.petshop; import jp.co.intra_mart.sample.web_api_maker.pet_shop.meta.pettag; import jp.co.intra_mart.sample.web_api_maker.pet_shop.model.pet; @IMAuthentication @PetShop public class PetService { @Path("/sample/pet-shop/pet/{id") @DELETE(summary = "ペット 情 報 を 削 除 します ", description = "ペット 情 報 を 削 除 します ") @PetTag public void delete(@required @Variable(name = "id", description = "ペットID") final int id) throws NotFoundException { for (final Pet p : ConstantData.PETS) { if (p.getid() == id) { // delete return; @Path("/sample/pet-shop/pet/{id") @GET(summary = "ペット 情 報 を 取 得 します ", description = "ペット 情 報 を 取 得 します ") @PetTag public Pet get(@required @Variable(name = "id", description = "ペットID") final int id) throws NotFoundException { for (final Pet pet : ConstantData.PETS) { if (pet.getid() == id) { return pet; @Path("/sample/pet-shop/pets") @POST(summary = "ペット 情 報 を 登 録 します ", description = "ペット 情 報 を 登 録 します ") @PetTag public void register(@required @Body final Pet pet) { // register @Path("/sample/pet-shop/pet/{id") @PUT(summary = "ペット 情 報 を 更 新 します ", description = "ペット 情 報 を 更 新 します ") @PetTag public void update(@required @Variable(name = "id", description = "ペットID") final int id, @Required @Body(description = "ペット 情 報 ") final Pet pet) throws NotFoundException { for (final Pet p : ConstantData.PETS) { if (p.getid() == id) { // update return; 注 意 APIドキュメントの 参 照 方 法 は API 仕 様 を 参 照 する を 参 照 してください 18
引 数 戻 り 値 に 指 定 可 能 な 型 Web API Maker ではHTTPメソッドやパラメータアノテーションごとに 受 け 取 り 可 能 な 型 が 異 なります 引 数 戻 り 値 に 指 定 可 能 な 型 は 以 下 になります 引 数 戻 り 値 に 指 定 可 能 な 型 (パラメータアノテーション 別 ) 型 @Parameter @Header @Variable @Body なし 戻 り 値 備 考 void byte[] 数 値 変 換 されず バイナリを 扱 います char[] String#toCharArray() と 等 価 InputStream 1 null @Bodyに 利 用 する 場 合 Swagger spec 出 力 に 非 対 応 InputStream[] 1 null Swagger spec 出 力 に 非 対 応 AttachmentFile 1 null AttachmentFile[] 1 null Swagger spec 出 力 に 非 対 応 boolean false 2 Boolean null 2 byte 0 2 Byte null 2 char 0 2 Character null 2 short 0 2 Short null 2 integer 0 2 Integer null 2 long 0 2 Long null 2 float 0 2 Float null 2 double 0 2 Double null 2 CharSequence null 2 Calendar null 2 Date null 2 Locale null 2 TimeZone null 2 URI null 2 URL null 2 UUID null 2 *[] 3 null List<*> 3 null Set<*> 3 null ServletRequest request 19
型 intra-mart Accel Platform Web API Maker プログラミングガイド 第 2 版 2015-12-01 @Parameter @Header @Variable @Body なし 戻 り 値 備 考 HttpServletRequest request ServletResponse response HttpServletResponse response (その 他 ) 1 null @Parameterに 利 用 する 場 合 Swagger spec 出 力 に 非 対 応 1 マルチパートのみ 指 定 可 3 *[] List<*> Set<*> それぞれの * は 2に 示 した 型 に 限 る 注 意 Swagger spec 出 力 に 関 しては Web 上 からAPI 仕 様 を 参 照 し 実 行 する を 参 照 してください 注 意 利 用 できない 型 を 指 定 した 場 合 intra-mart Accel Platform の 起 動 時 に 例 外 が 出 力 されます パッケージの 登 録 クラスパスに @WebAPIMaker が 付 与 されたファクトリクラスのパッケージを 列 挙 したファイルを 配 置 します 複 数 ある 場 合 は 複 数 行 にわけて 書 き 込 みます 例 として intra-mart e Builder for Accel Platform を 利 用 する 場 合 は 以 下 のようにファイルを 作 成 してください src/main/resources/meta-inf/im_web_api_maker/packages jp.co.intra_mart.sample.web_api_maker.pet_shop.service Web API Maker を 利 用 したAPIの 作 成 手 順 は 以 上 になります 20
作 成 したAPIの 利 用 について 項 目 利 用 方 法 セッション 管 理 API 仕 様 を 参 照 する Web 上 からAPI 仕 様 を 参 照 し 実 行 する 利 用 方 法 @Path で 指 定 した URL にアクセスすると REST-API が 実 行 可 能 です Web API Maker では データの 受 け 渡 しには 標 準 でJSON XMLの2 種 類 のフォーマットに 対 応 しています クライアントからのデータ 送 信 時 に ひとまとまりのオブジェクト 情 報 を 送 信 する 際 は オブジェクトを 各 フォーマットでリクエストボディに 含 める 事 が 可 能 です サーバからの 戻 り 値 も このフォーマットになります 利 用 するフォーマットはリクエストヘッダの 値 を 利 用 して 決 定 します リクエストヘッダ Content-Type メッセージボディにオブジェクトを 含 める 際 に 指 定 します JSONの 場 合 は application/json XMLの 場 合 は application/xml と 指 定 します リクエストヘッダ Accept 戻 り 情 報 のフォーマットを 指 定 します JSONの 場 合 は application/json XMLの 場 合 は application/xml と 指 定 します 404などのエラー 時 は 指 定 した 形 式 となる 保 証 はありません 戻 り 値 の 例 は 以 下 のようになります (application/json 場 合 ) { "error": false, "data": { "id": 1, "name": "Dog", "sold": false, "attibute": { "breed": "golden" { "error": true, "errormessage": "[E.IWP.WEBAPIMAKER.CONVERTER.10001] JSON 文 字 列 からの 変 換 に 失 敗 しました json:434343" コラム 値 がnullであるプロパティはJSON XML 共 に 出 力 されません また レスポンスされる HTTP ステータスは 以 下 の 通 りです レスポンスされる HTTP ステータスの 種 類 200 OK Accept ヘッダで 指 定 された MIME タイプで 処 理 結 果 を 返 却 します 400 Bad Request リクエストの 内 容 が 不 正 です Content-Type が application/json だが JSON 文 字 列 でない 等 が 考 えられます 401 Unauthorized 未 認 証 状 態 で 認 可 が 通 りません 403 Forbidden 認 証 済 み 状 態 ですが 認 可 が 通 りません 404 Not Found URL が 定 義 されていません 405 Method Not Allowed そのメソッドではアクセスできません 21
406 Not Acceptable Accept ヘッダに 指 定 されているタイプが 全 部 サポートしておらず レスポンスを 返 すことができません 415 Unsupported Media Type Content-Type ヘッダに 指 定 されているタイプがサポートしておらず リクエストを 読 むことができませ ん 500 Internal Server Error 内 部 サーバエラーです セッション 管 理 Web API Maker では リクエストヘッダー X-Intramart-Session を 指 定 することによりセッション 管 理 を 行 えます X-Intramart-Sessionには keep, once, never の3つの 値 が 利 用 できます ヘッダーを 省 略 した 場 合 は keep を 指 定 した 場 合 と 同 じ 挙 動 となります 指 定 した 値 による 挙 動 は 認 証 方 式 によって 以 下 のようになります X-Intramart-Session 動 作 IMAuthenticationの の 場 合 keep once never セッション 管 理 を 何 も 行 いません セッション 管 理 を 何 も 行 いません Web API 実 行 後 にログイン 状 態 である 場 合 ログアウトを 行 います BasicAuthenticationの の 場 合 X-Intramart-Session keep once never 動 作 認 証 済 みでない 場 合 は Web API 実 行 前 にログインを 行 います 実 行 後 は 何 も 行 いません 認 証 済 みでない 場 合 は Web API 実 行 前 にログインを 行 います Web API 実 行 前 に 未 認 証 であった 場 合 はログアウトを 行 います 認 証 済 みでない 場 合 は Web API 実 行 前 にログインを 行 います Web API 実 行 後 にログイン 状 態 である 場 合 ログアウ トを 行 います OAuthの の 場 合 X-Intramart-Session keep once never 動 作 認 証 済 みでない 場 合 は Web API 実 行 前 にログインを 行 います 実 行 後 は 何 も 行 いません 認 証 済 みでない 場 合 は Web API 実 行 前 にログインを 行 います Web API 実 行 前 に 未 認 証 であった 場 合 はログアウトを 行 います 認 証 済 みでない 場 合 は Web API 実 行 前 にログインを 行 います Web API 実 行 前 に 未 認 証 であった 場 合 はログアウトを 行 います API 仕 様 を 参 照 する 以 下 のURLにてAPIの 仕 様 を 返 すJSONを 取 得 可 能 です http://<host>:<port>/<context_path>/api-docs/${api-category ${api-category はサービスクラスで 指 定 している @Category アノテーションのvalue 値 になります 注 意 上 記 のAPI 仕 様 のURLは 認 可 によって 閲 覧 を 制 限 することが 可 能 です リソース 名 は Swagger specification です 認 可 については 認 可 仕 様 書 を 参 照 してください 注 意 API 仕 様 出 力 を 行 えるサービスクラスは @IMAuthentication が 付 与 されている 物 のみです @IMAuthentication が 付 与 されておらず @OAuth または @BasicAuthentication が 付 与 されているサービスクラスの 仕 様 は 出 力 で きません 22
Web 上 からAPI 仕 様 を 参 照 し 実 行 する 以 下 のURLにてswagger uiを 表 示 できます http://<host>:<port>/<context_path>/swagger_ui/ ページ 上 部 のテキストボックスにてAPI 仕 様 のURL( http://<host>:<port>/<context_path>/api-docs/${api-category)を 入 力 することで 仕 様 の 表 示 実 行 が 可 能 です 23
サンプルについて 項 目 サンプルアプリケーションの 仕 様 サンプルの 資 材 一 覧 Web API Maker には 簡 単 なWeb APIのサンプルが 含 まれています デプロイするには IM-Juggling で Web API Maker を 含 め なおかつサンプルを 含 める 設 定 で war を 作 成 してください warのデプロイ 後 テナント 環 境 セットアップ サンプルデータセットアップすることで 本 サンプルを 利 用 することができます サンプルアプリケーションの 仕 様 以 下 のURLにてAPIの 仕 様 を 返 すJSONを 取 得 可 能 です http://<host>:<port>/<context_path>/api-docs/petshop また 以 下 のURLにてswagger uiを 表 示 できます ページ 上 部 のテキストボックスにてAPI 仕 様 のURLを 入 力 することで 仕 様 が 表 示 可 能 です http://<host>:<port>/<context_path>/swagger_ui/ サンプルの 資 材 一 覧 サンプルのjavaソースは 最 新 情 報 ダウンロードページ(iAP) からダウンロードできます http://www.intra-mart.jp/download/product/iap/index.html 24
25