11.1 REST APIの概要
HTTPリクエスト
REST APIのリクエストURLは,次に示すように,ドメイン名,コンテキストルート,APIバージョンおよびリソースアクセスパスから構成されます。
http(s)://<ドメイン>/<コンテキストルート>/<APIバージョン>/<リソースアクセスパス>
ドメインはWebサーバで設定します。RESTサービスのコンテキストルートはcsciwwsです。APIバージョンは,v1,v2などREST APIのバージョンがAPIごとに固定値として設定されます。残りの部分がリソースにアクセスするためのパスです。
HTTPメソッド
CSCIWのREST APIで使用するHTTPメソッドを次の表で示します。
HTTPメソッド |
内容 |
---|---|
GET |
リソースを取得します。 |
POST |
リソースを新しく追加します。 |
PUT |
指定されたリソースを修正します。 |
DELETE |
指定されたリソースを削除します。 |
リクエストパラメタ
業務アプリケーションがRESTサービスにパラメタを渡す場合,クエリパラメタかリクエストボディを使用します。HTTPメソッドと,使用できるリクエストパラメタの関係を次の表で示します。
項番 |
リクエストパラメタ |
GET |
POST |
PUT |
DELETE |
---|---|---|---|---|---|
1 |
クエリパラメタ |
○ |
× |
× |
○ |
2 |
リクエストボディ |
△ |
○ |
○ |
× |
- (凡例)
-
○:利用できる
×:エラーが発生する
△:無視される
リクエストボディにパラメタを指定する場合,XML形式またはJSON形式で記載します。その際,HTTPヘッダのコンテンツタイプ(Content-Type)にapplication/xmlかapplication/jsonを指定する必要があります。コンテンツタイプにapplication/xmlかapplication/json以外の値が指定された場合や,未指定の場合はエラーになります。
使用できないリクエストパラメタを送信した場合,ステータスコード400のエラーが返されます。
リクエストボディに指定するパラメタをすべて省略する場合は,「リクエストパラメタ省略時のリクエストボディとHTTPヘッダ」を参照してください。
HTTPレスポンス
REST APIが正常終了した場合,HTTPレスポンスには,2xxのステータスコードが返されます。また,レスポンスボディにはリソースなどの情報が,XMLまたはJSON形式で返されます。コンテンツタイプはapplication/xmlまたはapplication/jsonです。レスポンスで返されるリソースの情報(プロセスデータは除く)については,マニュアルuCosminexus Service Coordinator Interactive Workflow AP開発ガイドの「付録B.1 指定できる属性一覧」を参照してください。
レスポンスの形式は,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" : "メッセージ本文" }
ユーザ記述子
REST APIが内部でJava APIを呼び出すとき,REST APIからJava APIにユーザ記述子を渡します。REST APIから渡すユーザ記述子のデフォルト値はcsciwwsです。デフォルト値とは異なるユーザ記述子を指定する場合は,共通設定ファイルのRestServiceUserDescriptionパラメタを変更するか,各REST APIのユーザ記述子のパラメタ(userdescription)を指定します。ユーザ記述子の長さは32バイト以下で指定してください。
ユーザ記述子については,マニュアルuCosminexus Service Coordinator Interactive Workflow AP開発ガイドの「createCIWServer」を参照してください。
データ型と文字コード
業務アプリケーションとRESTサービスのリクエストとレスポンスでやり取りされるデータ型は,数値,文字列,配列,日付です。日付は,yyyy-MM-dd'T'HH:mm:ssZの形式(ISO 8601の拡張形式)で表します(例:2016-06-09T10:32:41+09:00)。レスポンスの文字コードはUTF-8です。
また,無限遠の日付の場合は日付の形式ではなく定数で表します。無限遠の未来の場合はBEYONDとなり,無限遠の過去の場合はORIGINとなります。
オブジェクトの状態および種類
CSCIWのオブジェクトの状態および種類と,それに対応する定数名とコード値の対応を次の表に示します。レスポンスでは,コード値を文字列型で返します。状態の定数名とコード値については,マニュアルuCosminexus Service Coordinator Interactive Workflow AP開発ガイドの「付録B.2 指定できる属性値」の「(1)State属性で指定できる値」,および「付録C 状態遷移モデル」を参照してください。フローノードとフローノード定義の種類に関しては,定数名を返します。定数名の詳細については,次の記述を参照してください。
-
「12.9.2 CIWBPMNFlowNodeInstance.AttributeName(フローノードの属性名の列挙型)」
-
「12.9.3 CIWBPMNFlowNodeDefinition.AttributeName(フローノード定義の属性名の列挙型)」
-
「12.9.4 CIWBPMNFlowNodeDefinition.Type(フローノード定義におけるBPMN要素の種類の列挙型)」
状態および種類 |
定数名(コード値) |
---|---|
業務ステップの状態 |
INITIAL(i), READY(j), RUNNING(d), DISABLED(l), INTERMITTED(m), READY_FOR_TRANSITION(s), TRANSITION_COMPLETED(t), NOT_EXECUTED(p), TERMINATED(u), UNDEFINED(z) |
業務ステップの種類 |
NORMAL(0), UNDEFINED(z) |
ビジネスプロセス定義の状態 |
ACTIVE(b), INACTIVE(a), UNDEFINED(z) |
作業定義の種類 |
BUILTIN_CONCURRENT_WORK(b), NORMAL(0), UNDEFINED(z) |
案件の状態 |
NOT_STARTED(h), RUNNING(d), INTERMITTED(m), COMPLETED(o), TERMINATED(u), UNDEFINED(z) |
作業の状態 |
INITIAL(i), READY(j), EXECUTING(e), PERFORMING(f), NOT_EXECUTED(p), CANCELED(q), EXECUTED(r), DISABLED(l), INTERMITTED(m), TERMINATED(u), UNDEFINED(z) |
作業の種類 |
BUILTIN_CONCURRENT_WORK(b), NORMAL(0), UNDEFINED(z) |
XMLとJSONの相違点
- XMLの場合
-
-
リクエストボディとレスポンスにルート要素(<Parameter>や<ProcessInstances>など)を含みます。
-
タグを省略した場合にnullとして扱われます。
-
- JSONの場合
-
-
リクエストボディとレスポンスにルート要素を含みません。このため,各REST APIのリクエストボディとレスポンスの構造に記載されているルート要素は無視されます。
-
要素を省略した場合にnullとして扱われます。
-
Cosminexusアプリケーションサーバでは,値にnullが指定された場合は空文字として扱われます。
-
レスポンスの型が数値,またはboolean型の場合に,レスポンスはダブルクォーテーション「"」で囲われて返されます。
-
レスポンスの最大取得数
リソースの一覧を取得するREST APIの場合,レスポンスで取得できる最大データ件数を指定できます(デフォルト値は100件)。最大データ取得件数は,RestServiceResponseMaxCountパラメタにデフォルト値を設定するか,各REST APIの,リクエストパラメタに指定できます。
一覧取得のフィルター条件
リソースの一覧を取得するREST APIの場合,情報を絞り込むためのフィルター条件を設定できます。
日付型のデータを条件に指定する場合,1970/01/01 00:00:00 GMTを起点とした通算秒を指定する必要があります。日付が無限遠の過去の場合の通算秒は0となり,無限遠の未来の場合は9223372036854775となります。
Javaでの日付型データの変換例を次に示します。
SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssXXX"); Date date = format.parse("2016-01-01T00:00:00+09:00"); // 1970/01/01 00:00:00 GMT を起点とした通算ミリ秒を取得し,通算秒に変換 long second = date.getTime() / 1000L; String filterCondition = "StartDate<" + second;
ワーク管理データベースがPostgreSQLの場合,フィルター条件にPostgreSQLのC形式エスケープ(E'~')を使用することはできません。
一覧取得のソート条件
リソースの一覧を取得するREST APIの場合,ソート条件を設定できます。
ワーク管理データベースがPostgreSQLの場合,ソート条件にPostgreSQLのC形式エスケープ(E'~')を使用することはできません。
REST APIでのプロセスデータの扱い
- 単一型プロセスデータを扱う場合
-
REST APIで単一型プロセスデータを扱う場合,次に示すようにProcessDataタグにプロセスデータキー名とプロセスデータ値を指定します。
XMLの場合
<ProcessDataList> <ProcessData> <Key>$SProduct</Key> <Value>cake</Value> </ProcessData> <ProcessData> <Key>$NStock</Key> <Value>30</Value> </ProcessData> </ProcessDataList>
JSONの場合
"ProcessDataList" : { "ProcessData" : [ { "Key" : "$SProduct", "Value" : "cake" }, { "Key" : "$NStock", "Value" : "30" } ] }
- リスト型プロセスデータを扱う場合
-
REST APIでリスト型プロセスデータを扱う場合,次に示すように,key名の最後に{}を指定します。各データは定義されている順番にリスト化されます。また,リスト型プロセスデータの1要素を扱う場合は,key名の最後に{<リスト内識別子>}を指定します。
XMLの場合
<ProcessDataList> <ProcessData> <Key>$SProduct{}</Key> <Value>Bread</Value> </ProcessData> <ProcessData> <Key>$SProduct{}</Key> <Value>Butter</Value> </ProcessData> <ProcessData> <Key>$SProduct{}</Key> <Value>Strawberry</Value> </ProcessData> <ProcessData> <Key>$SProductCode{1}</Key> <Value>01234567895</Value> </ProcessData> </ProcessDataList>
JSONの場合
"ProcessDataList" : { "ProcessData" : [ { "Key" : "$SProduct{}", "Value" : "Bread" }, { "Key" : "$SProduct{}", "Value" : "Butter" }, { "Key" : "$SProduct{}", "Value" : "Strawberry" }, { "Key" : "$SProductCode{1}", "Value" : "01234567895" } ] }
リクエストパラメタ省略時のリクエストボディとHTTPヘッダ
一部のREST APIでは,リクエストボディに指定するパラメタをすべて省略できます。パラメタをすべて省略する場合は,リクエストボディを省略できます。リクエストボディを省略するときは,HTTPヘッダのContent-Typeを指定しないでください。リクエストボディを省略してContent-Typeを指定した場合の動作はサポートしません。
リクエストボディに指定するパラメタをすべて省略する場合のContent-Typeとリクエストボディの指定値を,次の表に示します。
項番 |
Content-Type |
リクエストボディ |
リクエストボディの例 |
---|---|---|---|
1 |
指定しない |
指定しない |
− |
2 |
application-xml |
ルート要素だけ指定する |
<Parameter/> |
3 |
application-json |
{}だけ指定する |
{} |
- (凡例)
-
−:該当しない