Web API Maker を利用した API の作成方法

この CookBook では、Web API Maker を利用した API の作成方法について紹介しています。
Web API Maker を利用したプログラミングは intra-mart Accel Platform Web API Maker プログラミングガイドに書かれていますが、この CookBook では簡易なサンプルプログラムを元に作成方法を紹介します。

完成イメージ

1. https://dev.intra-mart.jp/imart/im_cookbook/159976/get を開きます。
2. 以下のようなレスポンスが表示されます。（anonymous の部分はログイン時にはログインユーザコードが表示されます）

<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
<data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Hello anonymous</data>
<error>false</error>
</result>

<?xml version="1.0" encoding="ISO-8859-1"?>

<data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Hello anonymous</data>

<error>false</error>

</result>

完成サンプル

以下の完成サンプルをダウンロードしてご活用ください。

e builder プロジェクト : im_cookbook_152112.zip
imm ファイル : im_cookbook_159976-1.0.0.zip

ローカル環境で表示させる場合は、以下のURLにアクセスしてください。
http://localhost:8080/imart/im_cookbook/159976/get
なおベースURLである以下の部分は、環境に合わせて適宜変更してください。
http://localhost:8080/imart

レシピ

packages ファイルを作成します。
ファクトリを実装します。
サービスを実装します。
サービスにアクセスします。

1. packages ファイルを作成します。

以下のような packages ファイルを作成します。

src/main/resources/META-INF/im_web_api_maker/packages

jp.co.intra_mart.cookbook.cookbook159976

1	jp.co.intra_mart.cookbook.cookbook159976

ファイルの中身はパッケージを書いた一行のみです。
packages ファイルは拡張子も付けません。

このファイルを配置することで、パッケージ「jp.co.intra_mart.cookbook.cookbook159976」配下にある @WebAPIMaker アノテーションが付与されたクラスが Web API Maker に認識されるようになります。
逆に言えば、これから作成するファクトリやサービスクラスはパッケージ「jp.co.intra_mart.cookbook.cookbook159976」配下に作成します。

2. ファクトリを実装します。

src/main/java/jp/co/intra_mart/cookbook/cookbook159976/MyServiceFactory.java

package jp.co.intra_mart.cookbook.cookbook159976;

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 MyServiceFactory {
    @ProvideFactory
    public static MyServiceFactory getFactory() {
        return new MyServiceFactory();
    }

    @ProvideService
    public MyService getService() {
        return new MyService();
    }
}

package jp.co.intra_mart.cookbook.cookbook159976;

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 MyServiceFactory {

@ProvideFactory

public static MyServiceFactory getFactory() {

return new MyServiceFactory();

}

@ProvideService

public MyService getService() {

return new MyService();

}

行数	説明
7	ファクトリクラスには @WebAPIMaker アノテーションを付与します。
9-12	ファクトリ生成メソッドを定義します。単に、自身のインスタンスを new して返却します。
14-17	サービス生成メソッドを定義します。単に、サービスのインスタンスを new して返却します。

3. サービスを実装します。

src/main/java/jp/co/intra_mart/cookbook/cookbook159976/MyService.java

package jp.co.intra_mart.cookbook.cookbook159976;

import jp.co.intra_mart.foundation.context.Contexts;
import jp.co.intra_mart.foundation.context.model.AccountContext;
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;

@IMAuthentication
public class MyService {
    @Path("/im_cookbook/159976/get")
    @GET
    public String get() {
        final AccountContext context = Contexts.get(AccountContext.class);
        
        return "Hello " + context.getUserCd();
    }
}

package jp.co.intra_mart.cookbook.cookbook159976;

import jp.co.intra_mart.foundation.context.Contexts;

import jp.co.intra_mart.foundation.context.model.AccountContext;

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;

@IMAuthentication

public class MyService {

@Path("/im_cookbook/159976/get")

@GET

public String get() {

final AccountContext context = Contexts.get(AccountContext.class);

return "Hello " + context.getUserCd();

}

行数	説明
9	このサンプルでは特別な認証処理を行わないため @IMAuthentication アノテーションを付与します。
11	この API の URL を http://localhost:8080/imart/im_cookbook/159976/get と定義します。
12	この API には GET でアクセスできるように定義します。
13	メソッド名は何でも構いません。戻り値に API の戻り値とした型を指定します。
14-16	サービスメソッドを定義します。この API では Hello {ユーザコード} を返却します。

3. サービスにアクセスします。

Java で定義した API の戻り値は String ですが、REST API の戻り値は json もしくは xml になります。
リクエストヘッダー Accept に application/json を指定した場合、json で返却され、application/xml を指定した場合 xml で返却されます。

Accept: application/json でアクセス

curl -H "Accept: application/json" http://localhost:8080/imart/im_cookbook/159976/get

1	curl -H "Accept: application/json" http://localhost:8080/imart/im_cookbook/159976/get

以下のような json が返却されます

{"error":false,"data":"Hello anonymous"}

1	{"error":false,"data":"Hello anonymous"}

Accept: application/xml でアクセス

curl -H "Accept: application/xml" http://localhost:8080/imart/im_cookbook/159976/get

1	curl -H "Accept: application/xml" http://localhost:8080/imart/im_cookbook/159976/get

以下のような xml が返却されます

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><result><data xsi:type="xs:string" xmlns:xs="http://www.w3.org/2
01/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Hello anonymous</data><error>false</error></result>

1 2	<?xml version="1.0" encoding="UTF-8" standalone="yes"?><result><data xsi:type="xs:string" xmlns:xs="http://www.w3.org/2 01/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Hello anonymous</data><error>false</error></result>

このように単純な実装だけで、REST API を作成することが可能です。
是非ご活用ください。