付録I.8　運用管理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メソッドを次の表で示します。

ページの先頭へ

(3)　リクエストパラメタ

業務アプリケーションが運用管理RESTサービスにパラメタを渡す場合，クエリパラメタかリクエストボディを使用します。HTTPメソッドと，使用できるリクエストパラメタの関係を次の表で示します。

リクエストボディにパラメタを指定する場合，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のオブジェクトの状態と，それに対応する定数名とコード値の対応を次の表に示します。レスポンスでは，コード値を文字列型で返します。

ページの先頭へ

(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とリクエストボディの指定値を，次の表に示します。

ページの先頭へ