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 Code | HTTPステータスコード。 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のエラーなのかを切り分けてください。
XMLのネームスペース
http://www.hitachi.co.jp/soft/xml/jp1/itrm/api/errorを使用します。
XMLのスキーマ
APIからのエラー情報を格納するスキーマを次の表に示します。
エレメント | 説明 | データ型 | 出現回数 | |||
---|---|---|---|---|---|---|
階層1 | 階層2 | 階層3 | 最小 | 最大 | ||
error | - | - | エラー情報。 | - | 1 | 1 |
@product_version | - | VV-RR-SS(バージョン-リビジョン-限定コード)形式のJP1/ITRMの製品バージョン。 | xs:string | 1 | 1 | |
@api_version | - | 2桁の半角数字.2桁の半角数字形式のAPIのバージョン。 | xs:string | 1 | 1 | |
@datetime | - | エラー発生日時。 ISO8601形式かつUTCで出力する。 | xs:dateTime | 1 | 1 | |
@method | - | リクエストされたHTTPメソッド。 | xs:string | 1 | 1 | |
@url | - | リクエストされたURL。 | xs:string | 1 | 1 | |
message | - | メッセージ。 | xs:string | 1 | 1 | |
@message_id | メッセージID。 | xs:string | 1 | 1 | ||
text_msg | メッセージ(本文)。 4,095文字以内の文字列で表す。 | xs:string | 1 | 1 | ||
cause_msg | メッセージ(原因)。 4,095文字以内の文字列で表す。 | xs:string | 0 | 1 | ||
action_msg | メッセージ(対処)。 4,095文字以内の文字列で表す。 | xs:string | 0 | 1 |
出力例
認証情報が指定されていなかった場合の出力例を示します。
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>