JSON形式

ここでは、INFINI HOST-LINK InterNet版システム(以下本システム)においてINFINI内に設置されたアプリケーションサーバ(以下サーバ)と、ユーザ敷地内に設置されたサーバ(以下クライアント)との間のJSON形式のSabre Web Services(以下、SWS)機能利用に関するインタフェース仕様を記述する。
なお、ここではプロトコル層以上について記述し、ネットワークの物理層については範囲外とする。

基本仕様

1. サーバとクライアント間の通信はHTTP/1.0,1.1仕様に基づくHTTPプロトコルを用いるものとする。

2. 通信はすべてクライアントからの接続とし、サーバからの応答をもって完結する。
  ※ソケットの接続状態(Keep-Alive 制御)についてはIIS の実装に準じる。

3. セッションの概念を持たない HTTP 上においてセッション管理を実現するため、
  HTTP ヘッダを用いたセッション管理を行う(いわゆるクッキー方式を使用する)
  ※セッションとは、HOST-LINK サーバを経由してのINFINI ホストに対するサイン・イン(Sign in)から
  サイン・アウト(Sign out)までの接続状態を擬似的にHTTP プロトコル上に実現するものである。

4. また、クッキーのみでは制御できないプロトコルを実現するために、HTTP 拡張ヘッダを定義して使用する。

5. HTTPのコンテンツは各APIのリファレンスに準拠する事とし、本資料では関知しない。
  ※メッセージの先頭から連続する改行までをHTTPヘッダとし、以降をコンテンツと呼ぶ。

6. メッセージはヘッダー、コンテンツともすべてASCII 文字で構成されるものとする。
  (現時点で本システムにおいて日本語などのマルチバイト文字は使用しない)

7. 本サービスは下記のURL で提供される。
  本番環境:https://www.infini-hostlink.com/HostLinkService/infiniAPI.asp
  テスト環境:https://testsite.infini-hostlink.com/HostLinkService/infiniAPI.asp

8. 未承認ユーザからのアクセスについて
  ユーザ登録には、ユーザ側サーバIP アドレスと利用PCC を必要とする。
  登録されたIP アドレスや指定されたPCC以外からのアクセスに対し、本システムは特にエラー回答はせず、
  HTTP メッセージのみを回答する。

構成

本仕様を実現するための、構成(案)を付図に示す。
※ なお、クライアント側構成については想像に基づくものである。



※クライアント(Agent System)側はなんらかのアプリケーションサーバ機能により、
 サーバ(INFINI System)より付与されたCookie 値を維持することを想定する。

セッションの管理

各セッションのフェーズに応じて、下記の拡張ヘッダを含むHTTP ヘッダが送付されるものとする。

<セッションの開始>
1. セッションの開始時にクライアントは、下記 HTTP ヘッダを持つリクエストメッセージを送信する。
  X-XML-Booking-Session: SESSION=START
  X-XML-Booking-PCC: PCC=XXXX
  X-XML-Booking-Host: HOST=SWS
  X-XML-Booking-Mode: MODE=REST

  ※XXXXは旅行会社の持つ4桁のPCCコードであり、サイン・インに使用される。
   また、サーバでPCCコードの末尾が"6"であることをチェックする。

  ※コンテンツデータはtext/*(もしくはtext/json、application/json)形式で送受信される。
  ※セッション確立中でのホスト接続先変更(HOST→SWSまたはSWS→HOST)は不可とする。
   HOSTセッション接続中にSWSにセッション開始を行うと、HOSTセッションは終了しない。
   (SWS→HOSTも同様)
  ※セッション確立中でのモード変更(MODE=REST→MODE指定なし または
   MODE=指定なし → MODE=REST)は現時点では不可とする。
  ※X-XML-Booking-Session: SESSION=START_ENDによるセッション開始、エントリ実行、
   セッション終了の1リクエストによる実行も可能とする。


2. 上記要求に対しサーバは、SWS(Sabre Web Service)との接続を確立し、その結果を、
  下記HTTPヘッダーを持つレスポンスメッセージによりクライアントに送信する。
  X-XML-Booking-Status: STATUS=XXXX
  Set-Cookie: ASPSESSIONIDYYYYY=ZZZZZ; ….
  ※XXXXはソケットの確立、およびサイン・インの結果を示すステータス・コードである。
   このステータスが異常の場合には Set-Cookie ヘッダは送られない。
  ※クライアントは通知されたクッキー情報(ASPSESSIONIDYYYYY=ZZZZZ)を記憶しておく。
   (YYYYY,ZZZZZは任意の長さの文字列である)
  ※クッキー情報内の";"以降の文字列についてはクライアントで無視する(付かない場合もある)。

  ※"Set-Cookie"という識別子を持つヘッダ情報は単一ではないため、それぞれ取得する必要がある。
  ※セッションが存在する時点でクライアントよりセッション開始要求を行った場合、
   サーバはホストからサイン・アウトして再度、サイン・インする。


<セッションの維持>

1. クライアントはセッション継続中のリクエストメッセージには、下記 HTTP ヘッダを付けて送信する。
  (1) X-XML-Booking-Host: HOST=SWS
  (2) X-XML-Booking-Mode: MODE=REST
  (3) Cookie: ASPSESSIONIDYYYYY=ZZZZZ
  ※ Cookie 情報はセッション開始時にサーバから返された情報であること。


2. 上記要求に対しサーバは、コンテンツデータを処理し、その結果を、下記HTTP ヘッダーを持つ
  レスポンスメッセージによりクライアントに送信する。
  X-XML-Booking-Status: STATUS=XXXX


<セッションの終了>

1. クライアントはセッションを終了させるために、下記 HTTP ヘッダを持つリクエストメッセージを送信する。

 (1)   X-XML-Booking-Host: HOST=SWS
   X-XML-Booking-Mode: MODE=REST
   Cookie: ASPSESSIONIDYYYYY=ZZZZZ
   X-XML-Booking-Session: SESSION=END

 (2)   X-XML-Booking-Host: HOST=SWS
   X-XML-Booking-Mode: MODE=REST
   X-XML-Booking-Session: SESSION=START_END

※ (2)の場合はセッション開始、終了を同時に行う。
※ Cookie 情報はセッション開始時にサーバから返された情報であること。


2. 上記要求に対しサーバは、下記HTTPヘッダを持つレスポンスメッセージを送信する。
   X-XML-Booking-Status: STATUS=XXXX
  ※XXXXはソケットの切断、およびサイン・アウトの結果を示すステータス・コードである。


<サーバー障害に伴うセッション終了>

1. サーバにおいてリクエスト受信後に、処理を継続できない状況が生じた場合、サーバは
  下記HTTP ヘッダを持つレスポンスメッセージを送信する。
   X-XML-Booking-Session: SESSION=END
   X-XML-Booking-Status: STATUS=XXXX

  ※ XXXX は障害を示すステータスとする。
  ※ホストのタイムアウト、対ホストソケットの切断などを想定しているため、
   セッションは切断されることを前提とする。
  ※セッション開始リクエスト受信時に障害が起きた場合、レスポンスメッセージに上記のヘッダ以外に
   Set-Cookie: が指定されるかもしれないが、クライアントはこれを用いたリクエストを行ってはならない。
  ※クライアントより受信したリクエストのHTTPヘッダが不適当な場合はエラー応答を行い、
   セッションを切断する。


2. 同様にリクエスト受信後に、応答も返せない状況が生じた場合、クライアントは一定時間受信を待った後
  セッションを切断すること。



<クライアント障害に伴うセッションタイムアウト>

1. クライアントにおいて処理を継続できない状況が生じた場合、上記「セッションの終了」と
  同じ手順によりセッション終了要求を行うこと。

2. セッション終了要求も送信できない状況が生じた場合、サーバは一定時間セッションを維持した後、
  セッションを終了させる。

HTTPメソッド、Endpointの指定

本システムはREST形式のコンテンツを各HTTPメソッド(POST、GET等)で受け付ける。
また、各コンテンツのEndpointの指定については下記HTTPリクエストヘッダーにより指定するものとする。

Endpointの指定例
X-XML-BOOKING-ENDPOINT: /v2.1.0/get/hotelavail

   ※上記「v2.1.0」部分がバージョンになります。
   ※HTTPメソッド、Endpointの詳細は、機能仕様書を参照のこと。

コンテンツ

通常コンテンツには、SWS(Sabre Web Service)仕様に基づく JSONメッセージあるいはテキストメッセージが
含まれるが、下記のヘッダが付いた場合には、そのメッセージのコンテンツは無視するものとする
(サーバ、クライアント双方において)。

※ 下記ヘッダーがついたメッセージのコンテンツはSabre仕様に含まれない独自コンテンツとする。
  X-XML-Booking-Contents: CONTENTS=IGNORE

例 1: クライアントから、セッション開始/セッション終了のみ行う場合のリクエスト/レスポンスメッセージ
例 2: サーバにて障害が発生した場合のレスポンスメッセージ

コンテンツのGZIP圧縮
通常コンテンツは非圧縮のJSONメッセージを戻すが、下記HTTPレスポンスヘッダーが含まれる場合、
コンテンツがGZIP圧縮されているためクライアント側で解凍するものとする。
   Content-Encoding: gzip

クライアントからの下記HTTPリクエストヘッダーについて本システムでは受け付けない。
仮に送信されてきても無視する。
   Accept-Encoding

通信例

上記仕様に基づいた通信例は以下の通りである。

通常パターン



セッション開始要求のみ先行するパターン



セッション終了要求のみクライアントから送信するパターン



セッションタイムアウト終了後にクライアントから要求を送信するパターン



クライアントセッション開始要求と終了要求の両方が指定されたパターン



クライアントセッション開始要求と終了要求の両方(SESSION=START_END)が指定されたパターン

 

セキュリティ

1. 本システムにおいて、INFINI 側LAN とユーザ側LAN 間の通信(WAN)については物理層によって
  十分セキュリティが確保されていることを前提とし、この部分のセキュリティ対策は本設計書では記述しない。
2. INFINI 側LAN 内部およびユーザ側LAN 内部におけるセキュリティ保持のため、サーバにおいて下記の対策を取る。

リクエストメッセージ送信元の確認
1. リクエストメッセージ送信元のIP アドレスをチェックし、あらかじめ設定された
  IP アドレス以外からのリクエストはエラー応答し、該当セッションを切断する。
2. セッション開始時の送信元IP アドレスを記憶しておき、セッション途中ではそのIP アドレス
  以外からの要求はエラー応答する。

セッションのタイムアウト
1. 一定時間リクエストの無いセッションについては、サーバでこれを無効化する。
2. 無効化されたセッションを指定したリクエストメッセージについては、エラー応答する。
  この場合の HTTP ヘッダは下記の通りとする。
   X-XML-Booking-Session: SESSION=END
   X-XML-Booking-Status: STATUS=9C00
   X-XML-Booking-Contents: CONTENTS=IGNORE

 ※ ただし、そのメッセージがセッション開始要求の場合は正常リクエストとみなし、
   新規セッションを開始する。
 ※ タイムアウト値は5分とする。

受信コンテンツサイズの制限
ありえないサイズのリクエストを受信することによるメモリ不足や高負荷の発生を予防するため、
受信中のコンテンツサイズが32KB を超えた時点で以降の受信を中止しエラー応答する。
 

特記

1.  ステータス・コードについては、付録に一覧を添付する。
2.  本設計書のセッション管理方法は、RFC2109(HTTP State Management Mechanism)に準拠する。
3.  HTTP 拡張ヘッダは、RFC822(STANDARD FOR THE FORMAT OF ARPA INTERNET
   TEXT MESSAGES)に準拠し、先頭文字を "X-"とする。
4.  また、RFC2616 に準拠し HTTP ヘッダ識別子(":"の左側の文字列)において大文字/小文字は
   区別されないものとする。
5.  特に断りの無い限り、サーバより送信するHTTP メッセージ仕様は IIS7.5 の実装に依存する。

付録<INFINI HOST-LINK XML版ステイタス・コードについて>

現在のINFINI HOST-LINK XML 版に基づいて返されるステータス・コード(拡張ヘッダの
STATUS に設定される値)は下記の定義に従った16 進4 桁数値である。

エラーコード

エラーコード       エラー内容       
0000 正常
9401 PCC エラー(末尾が6 でない、または長さが8 バイトより長い)
9402 不正なアクセス(途中で IP アドレスが未登録 IP アドレスに変更された)
9403 不正なアクセス(未登録 IP アドレスから受信)
9404 コンテンツが長すぎる(32KB を超えている)
9406 認識できないヘッダーがある
9407
(Sxxx)
サイン・イン・エラー
xxxx はホスト・エラー・コード
9408 PCC セッション上限数オーバー
9409 許可されていないコマンド
940C 不正なクッキー
940D 不正なアクセス(接続先にMODE=RESTが指定されていない)
9C00 ホストとの接続時エラー
セッションが存在しない
A402 ホストからの受信エラー
受信タイムアウト
A405 ホスト、サーバータイムアウト
A8FF 受信したレスポンス・データが空だった
AC01
(xxx)
SWS ホスト通信エラー
SWS ホストへのコマンド送受信時のHTTP ステータスコードが200 でない
xxx はステータスコード
AC03
(SWS)
ホストビジー
通信毎にスレッド数の上限数オーバー
FFFF 内部エラー