intra-mart Accel Platform Web API Maker プログラミングガイド 第5版 2019-04-01

5. 作成したAPIの利用について

5.1. 利用方法

@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
そのメソッドではアクセスできません。
406 Not Acceptable
Accept ヘッダに指定されているタイプが全部サポートしておらず、レスポンスを返すことができません。
415 Unsupported Media Type
Content-Type ヘッダに指定されているタイプがサポートしておらず、リクエストを読むことができません。
500 Internal Server Error
内部サーバエラーです。

5.2. セッション管理

Web API Maker では、リクエストヘッダ X-Intramart-Session を指定することによりセッション管理を行えます。
X-Intramart-Sessionには、 keep , once , never の3つの値が利用できます。
ヘッダを省略した場合は keep を指定した場合の挙動と同じです。
指定した値による挙動は認証方式によって以下のように異なります。
IMAuthenticationの場合
X-Intramart-Session 動作
keep セッション管理を何も行いません。
once セッション管理を何も行いません。
never Web API実行後にログイン状態である場合、ログアウトを行います。
BasicAuthenticationの場合
X-Intramart-Session 動作
keep 認証済みでない場合は、Web API実行前にログインを行います。実行後は何も行いません。
once 認証済みでない場合は、Web API実行前にログインを行います。Web API実行前に未認証であった場合はログアウトを行います。
never 認証済みでない場合は、Web API実行前にログインを行います。Web API実行後にログイン状態である場合、ログアウトを行います。
OAuthの場合
X-Intramart-Session 動作
keep 認証済みでない場合は、Web API実行前にログインを行います。実行後は何も行いません。
once 認証済みでない場合は、Web API実行前にログインを行います。Web API実行前に未認証であった場合はログアウトを行います。
never 認証済みでない場合は、Web API実行前にログインを行います。Web API実行前に未認証であった場合はログアウトを行います。

5.3. 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 が付与されているサービスクラスの仕様は出力できません。

5.4. Web上からAPI仕様を参照し実行する

以下のURLにてswagger uiを表示できます。
  • http://<HOST>:<PORT>/<CONTEXT_PATH>/swagger_ui/
ページ上部のテキストボックスにてAPI仕様のURL(http://<HOST>:<PORT>/<CONTEXT_PATH>/api-docs/${api-category})を入力することで仕様の表示、実行が可能です。
swagger_ui