8. REST API¶
REST APIについて説明します。
8.1. REST APIについて¶
履歴・コメントモジュールが提供するREST APIは、HTTPプロトロルを使用し履歴・コメントモジュールに関する様々な処理を呼び出すことが可能です。
REST APIはコンテンツタイプとして、application/json (JSON)形式のみ対応しています。
REST APIとして利用可能な機能は以下のとおりです。
- 添付ファイル
- コメント
- イベント
- 認証情報
8.2. 認証方式¶
REST APIは以下の認証方式に対応しています。
Cookieに紐づくセッションの認証状態に依存する方式
アプリケーションサーバが発行するセッションIDおよびアカウントコンテキストの状態に依存する方式です。コンテキストの状態を確認後、認可によるチェックが行われます。Basic認証
Basic認証による認証方式です。認証後、ログイン状態として扱われ認可によるチェックが行われます。OAuth認証
OAuth2.0の仕様に準拠した認証フローによる認証方式です。認証後、ログイン状態として扱われ認可によるチェックが行われます。
コラム
Basic認証を利用する場合には、httpsプロトコルの利用を強く推奨します。
8.3. 認可¶
REST APIは全ての呼び出しに対し認可リソースを持ちます。
intra-mart Accel Platform認可設定において、「画面・処理」リソースの「履歴・コメントモジュール」で変更できます。
注意
履歴・コメントモジュールの標準機能では、画面表示に必要となる情報を全てREST API経由で取得しています。
その為、認可設定の変更により画面が正常に動作しなくなる場合があります。
8.4. エンドポイント¶
REST APIは認証方式によって、呼び出し先のエンドポイントが異なります。
Cookieに紐づくセッションの認証状態に依存する方式
http(s)://{HOST}:{PORT}/{CONTEXT_PATH}/api/journal/....プロトコル、ホスト名、ポート番号、コンテキストパスは環境にあわせて置き換えてください。例:https://example.org/imart/api/journal/eventsBasic認証
http(s)://{HOST}:{PORT}/{CONTEXT_PATH}/api/basic/journal/....プロトコル、ホスト名、ポート番号、コンテキストパスは環境にあわせて置き換えてください。例:https://example.org/imart/api/basic/journal/eventsOAuth認証
http(s)://{HOST}:{PORT}/{CONTEXT_PATH}/api/bearer/journal/....プロトコル、ホスト名、ポート番号、コンテキストパスは環境にあわせて置き換えてください。例:https://example.org/imart/api/bearer/journal/events
8.5. Swagger¶
REST APIはSwagger Specに対応しています。
intra-mart Accel Platformに組み込まれているSwagger UIを通じてREST APIの確認、実行ができます。
Swagger UIは、以下のURLから確認できます。
http(s)://{HOST}:{PORT}/{CONTEXT_PATH}/swagger_ui/?url=/{CONTEXT_PATH}/api-docs/IM-journalプロトコル、ホスト名、ポート番号、コンテキストパスは環境にあわせて置き換えてください。例:https://example.org/imart/swagger_ui/?url=/imart/api-docs/IM-journal
コラム
Swagger Specを元に、Swagger CodeGenを利用するとREST APIクライアントコードの自動生成を行うことが可能です。
Swagger CodeGenにより作成されたスタブコードの動作保証は行っておりません。
8.6. REST APIドキュメント¶
APIの詳細に関しては、「 履歴・コメントモジュール Rest 」を御覧ください。
8.7. イベントグループキーについて¶
イベントグループを一意に設定するためのキーとしてイベントグループキーをREST APIに送信する必要があります。
イベントグループキーは、リクエストパラメータに設定してください。
イベントグループキーは、リクエストパラメータの以下を除くキーとその値から生成されます。
- count
- index
- sortOrder
- eventTypeIds
- _（アンダスコア）
- application
- access_token
コラム
例:
https://example.org/imart/api/journal/event_count?application=APPLICATION1&eventGroupKey1=value1&eventGroupKey2=value2
application は除かれ、 その他の eventGroupKey1 と eventGroupKey2 でイベントグループキーが生成されます。
イベントグループキー: { eventGroupKey1: ‘value1’, eventGroupKey2: ‘value2’ }