付録I.8 運用管理REST APIの構成要素
運用管理REST APIの構成要素について説明します。
- 〈この項の構成〉
(1) HTTPリクエスト
運用管理REST APIのリクエストURLは,次に示すとおり,ドメイン名,コンテキストルート,APIバージョンおよびリソースアクセスパスから構成されます。
http(s)://<ドメイン>/<コンテキストルート>/<APIバージョン>/<リソースアクセスパス>
ドメインはWebサーバで設定します。運用管理RESTサービスのコンテキストルートはcsciwmngwsです。APIバージョンは,v1,v2など運用管理REST APIのバージョンがAPIごとに固定値として設定されます。残りの部分がリソースにアクセスするためのパスです。
(2) HTTPメソッド
CSCIWの運用管理REST APIで使用するHTTPメソッドを次の表で示します。
HTTPメソッド |
内容 |
---|---|
GET |
リソースを取得します。 |
POST |
リソースを新しく追加します。 |
PUT |
指定されたリソースを修正します。 |
DELETE |
指定されたリソースを削除します。 |
(3) リクエストパラメタ
業務アプリケーションが運用管理RESTサービスにパラメタを渡す場合,クエリパラメタかリクエストボディを使用します。HTTPメソッドと,使用できるリクエストパラメタの関係を次の表で示します。
項番 |
リクエストパラメタ |
GET |
POST |
PUT |
DELETE |
---|---|---|---|---|---|
1 |
クエリパラメタ |
○ |
× |
× |
○ |
2 |
リクエストボディ |
△ |
○ |
○ |
× |
リクエストボディにパラメタを指定する場合,XML形式またはJSON形式で記載します。その際,HTTPヘッダのコンテンツタイプ(Content-Type)にapplication/xmlかapplication/jsonを指定する必要があります。コンテンツタイプにapplication/xmlかapplication/json以外の値が指定された場合や,未指定の場合はエラーになります。
使用できないリクエストパラメタを送信した場合,ステータスコード400のエラーが返されます。
リクエストボディに指定するパラメタをすべて省略する場合は,「付録I.8(10) リクエストパラメタ省略時のリクエストボディとHTTPヘッダ」を参照してください。
(4) HTTPレスポンス
運用管理REST APIが正常終了した場合,HTTPレスポンスには,2xxのステータスコードが返されます。また,レスポンスボディにはリソースなどの情報が,XMLまたはJSON形式で返されます。コンテンツタイプはapplication/xmlまたはapplication/jsonです。レスポンスで返されるリソースの情報(プロセスデータは除く)については,マニュアル「uCosminexus Service Coordinator Interactive Workflow AP開発ガイド」の「指定できる属性一覧」の説明を参照してください。
レスポンスの形式は,HTTPヘッダの"Accept"にapplication/xmlまたはapplication/jsonを指定すると切り替わります。application/xmlまたはapplication/json以外の値が指定された場合はエラーになります。"Accept"が未指定の場合はXML形式で返されます。
運用管理REST APIがエラーになった場合,HTTPレスポンスには,3xx,4xxまたは5xxのステータスコードが返されます。また,レスポンスボディには次に示すようなエラードキュメントが返されます。エラーを受け取ったクライアントは,返却されたHTTPレスポンスと,ステータスコードに従ってエラーに対処できます。HTTPレスポンスのボディに設定しているメッセージにはエラーの詳細情報は付与されません。発生したエラーの詳細情報については,運用管理REST APIのログファイルを確認してください。
- エラー時のレスポンスボディ(XMLの場合)
<?xml version="1.0" encoding="UTF-8"?> <error> <code>KDIWnnnnn-E</code> <message>メッセージ本文</message> </error>
- エラー時のレスポンスボディ(JSONの場合)
{ "code" : "KDIWnnnnn-E", "message" : "メッセージ本文" }
(5) ユーザ記述子
運用管理REST APIが内部でJava APIを呼び出すとき,運用管理REST APIからJava APIにユーザ記述子を渡します。運用管理REST APIから渡すユーザ記述子のデフォルト値はcsciwmngwsです。デフォルト値とは異なるユーザ記述子を指定する場合は,セットアッププロパティファイルのMngRestServiceUserDescriptionキーを変更するか,各運用管理REST APIのユーザ記述子のパラメタ(userdescription)を指定します。なお,ユーザ記述子は32バイト以下の長さにしてください。
(6) データ型と文字コード
業務アプリケーションと運用管理RESTサービスのリクエストとレスポンスでやり取りされるデータ型は,数値,文字列,配列,日付です。日付は,yyyy-MM-dd'T'HH:mm:ssZの形式(ISO8601の拡張形式)で表します(例:2016-06-09T10:32:41+09:00)。レスポンスの文字コードはUTF-8です。
また,無限遠の日付の場合は日付の形式ではなく定数で表します。無限遠の未来の場合はBEYONDとなり,無限遠の過去の場合はORIGINとなります。
(7) オブジェクトの状態
CSCIWのオブジェクトの状態と,それに対応する定数名とコード値の対応を次の表に示します。レスポンスでは,コード値を文字列型で返します。
状態 |
定数名(コード値) |
---|---|
ビジネスプロセス定義の状態 |
ACTIVE(b),INACTIVE(a),UNDEFINED(z) |
振り分けルール定義の状態 |
ACTIVE(b),INACTIVE(a),UNDEFINED(z) |
(8) XMLとJSONの相違点
- XMLの場合
-
-
リクエストボディとレスポンスにルート要素(<Parameter>や<ProcessInstances>など)を含みます。
-
タグを省略した場合にnullとして扱われます。
-
- JSONの場合
-
-
リクエストボディとレスポンスにルート要素を含みません。このため,各運用管理REST APIのリクエストボディとレスポンスの構造に記載されているルート要素は無視されます。
-
要素を省略した場合にnullとして扱われます。
-
Cosminexusアプリケーションサーバでは,値にnullが指定された場合は空文字として扱われます。
-
レスポンスの型が数値,またはboolean型の場合に,レスポンスはダブルクォーテーション「"」で囲われて返されます。
-
(9) レスポンスの最大取得件数
運用管理RESTサービスの一覧取得APIの場合,レスポンスで取得できる最大件数を指定できます。最大件数のデフォルト値は100件です。最大取得件数は,セットアッププロパティファイルのMngRestServiceResponseMaxCountキーに設定するか,運用管理REST APIのリクエストパラメタに指定できます。
(10) リクエストパラメタ省略時のリクエストボディとHTTPヘッダ
一部の運用管理REST APIでは,リクエストボディに指定するパラメタをすべて省略できます。パラメタをすべて省略する場合は,リクエストボディを省略できます。リクエストボディを省略するときは,HTTPヘッダのContent-Typeを指定しないでください。リクエストボディを省略してContent-Typeを指定した場合の動作はサポートしません。
リクエストボディに指定するパラメタをすべて省略する場合のContent-Typeとリクエストボディの指定値を,次の表に示します。
項番 |
Content-Type |
リクエストボディ |
リクエストボディの例 |
---|---|---|---|
1 |
指定しない |
指定しない |
— |
2 |
application-xml |
ルート要素だけ指定する |
<Parameter/> |
3 |
application-json |
{}だけ指定する |
{} |