API共通の仕様

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

通信プロトコル
HTTPを使用します。HTTPのバージョンは，1.0以降です。
HTTPリクエストや，HTTPレスポンスなどのHTTPプロトコルの詳細な仕様については，RFC1945およびRFC2068で規定されている仕様に従ってください。
文字コード
UTF-8を使用します。
ポート番号
デフォルトは，23505です。ポート番号は，新規にJP1/ITRMをインストールまたはセットアップする場合に指定できます。詳細については，マニュアル「JP1/IT Resource Management - Manager 設計・構築ガイド」のインストールに関する手順またはセットアップ手順を参照してください。また，ポート番号を変更する場合は，jirmsetportnoコマンドを使用してください。jirmsetportnoコマンドの詳細については，「jirmsetportno」（1.　コマンド）を参照してください。
認証方式
BASIC認証にだけ対応しています。

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

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

（凡例）　△：半角スペース

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

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

API実行時にヘッダーフィールド（Authorization）で指定された認証情報を使用して，JP1/ITRMにログインできる。
API実行時にヘッダーフィールド（Authorization）で指定されたJP1/ITRMのユーザーに，ロールID：_jp1resourceが割り当たっている。

参考

APIクライアントごとに，API専用のユーザーを追加し，そのユーザーにロールID：_jp1resourceを割り当てることをお勧めします。ユーザーの追加およびロールの割り当てについては，マニュアル「JP1/IT Resource Management - Manager 設計・構築ガイド」のユーザーとロールの管理についての説明を参照してください。

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

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	－	－	エラー情報。	－	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>