API共通の仕様

API共通の仕様を次に示します。

通信プロトコル

APIとの通信プロトコルの詳細を次に示します。

HTTPリクエスト形式

APIに対するHTTPリクエスト形式には,Method,URI,Query String,ヘッダーフィールドを指定します。Method,URI,およびQuery Stringは,各機能のHTTPリクエスト形式を参照してください。ヘッダーフィールドは,次のとおり指定してください。

Authorization:△Basic△BASE64でエンコードしたJP1/ITRMのユーザー名およびパスワード

(凡例) △:半角スペース

なお,ヘッダーフィールド(Authorization)に指定する形式の詳細な仕様については,RFC2617で規定されている仕様に従ってください。

APIの発行元の認証

APIは,APIの発行元(APIの利用者)を認証します。APIクライアントからHTTPリクエストとして受信した認証情報が,次の2つの条件を満たしているかを検証します。

HTTPレスポンス形式

HTTPリクエストに対するレスポンスは,XMLを使用します。

HTTPレスポンスの項目を次の表に示します。

項目
Status CodeHTTPステータスコード。
HTTPステータスコードについては,「HTTPステータスコード」を参照してください。
ヘッダーフィールドContent-Type: application/xml
Content-Length: Bodyのサイズ
Bodyなし,またはXML。
XMLについては,各機能の「XMLのスキーマ」を参照してください。

HTTPステータスコード

APIから返却するHTTPステータスコードを次の表に示します。

HTTPステータスコード説明
200 OK正常。
HTTPリクエストは成功し,要求に応じた情報が返却される。
202 Accepted受理。
リクエストは受理されたが,処理は完了していない。
400 Bad Request指定したリクエストが誤っている。
401 Unauthorized認証情報が未設定または誤っている。
405 Method Not Allowed指定したHTTPメソッドが未サポートである。
500 Internal Server Errorサーバ側でリクエストした内容を完了できなかった。

なお,JP1/ITRMのWebサーバでエラーが発生した,通信障害が発生したなど,このHTTPステータスコード以外のステータスコードが返却されることがあります。この場合,HTTPレスポンス形式のBodyの形式が,XML形式になりません。

エラー情報

APIの処理が異常終了した場合に返却するエラー情報について説明します。

なお,エラー情報として返却するメッセージは,APIクライアントの開発者向けのメッセージです。ITリソース利用者向けのメッセージではありません。そのため,APIが返却したメッセージをAPIクライアントの利用者に表示することは想定していません。

APIクライアントの開発者は,HTTPレスポンス形式のHTTPステータスコードを使って,エラーの要因が,リクエスト内容の誤りなのかJP1/ITRMのエラーなのかを切り分けてください。

注意
HTTPレスポンス形式のBodyに含まれるエラーメッセージID,メッセージテキスト,要因および対処は,JP1/ITRMのバージョンアップに伴い変更されることがあります。そのため,APIクライアントを実装するときのプログラミングの条件にしないでください。また,メッセージの文字列を解析しないでください。

XMLのネームスペース

http://www.hitachi.co.jp/soft/xml/jp1/itrm/api/errorを使用します。

XMLのスキーマ

APIからのエラー情報を格納するスキーマを次の表に示します。

エレメント説明データ型出現回数
階層1階層2階層3最小最大
errorエラー情報。11
@product_versionVV-RR-SS(バージョン-リビジョン-限定コード)形式のJP1/ITRMの製品バージョン。xs:string11
@api_version2桁の半角数字.2桁の半角数字形式のAPIのバージョン。xs:string11
@datetimeエラー発生日時。
ISO8601形式かつUTCで出力する。
xs:dateTime11
@methodリクエストされたHTTPメソッド。xs:string11
@urlリクエストされたURL。xs:string11
messageメッセージ。xs:string11
@message_idメッセージID。xs:string11
text_msgメッセージ(本文)。
4,095文字以内の文字列で表す。
xs:string11
cause_msgメッセージ(原因)。
4,095文字以内の文字列で表す。
xs:string01
action_msgメッセージ(対処)。
4,095文字以内の文字列で表す。
xs:string01
(凡例)
-:なし。

出力例

認証情報が指定されていなかった場合の出力例を示します。

HTTP/1.1 401 Unauthorized
Content-Length: 500
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<error product_version="09-51-01" api_version="01.00"
datetime="2011-08-26T05:11:11.250Z" method="POST"
url="http://localhost:23505/jp1itrm/api/instances/1/start?realm=1"
xmlns="http://www.hitachi.co.jp/soft/xml/jp1/itrm/api/error">
<message message_id="KNAR96111-E">
<text_msg>認証情報が指定されていません。(指定されたURI=/jp1itrm/api/instances/1/start?realm=1) </text_msg>
<cause_msg>HTTPリクエストに認証情報が指定されていません。</cause_msg>
<action_msg>HTTPリクエストには正しい認証情報を指定してください。</action_msg>
</message>
</error>