http://localhost:50000/fusionplace/api/1.2/requests
Web API 解説
目次
Web API とは
[Web API] とは、fusion_place の機能を使用するプログラムを開発するための、アプリケーション・プログラム・インターフェース（API）です。[Web API] は HTTP プロトコルベースですので、開発言語を問わず、多様なプログラムから使用することができます。
なお、[Web API] に関する以下の解説は、HTTP プロトコルに関する基本的知識を前提としています。
Web API でできること
[Web API] では、以下の通り、 リクエスタ と同様の処理を実行することができます。
[Web API] でのリクエストの書式は、リクエスタのリクエストファイルの書式とほとんど同じです。実際、リクエスタは、リクエストを fusion_place に送信し、レスポンスを受信するために、[Web API] を使用しています。
Web API の使用可能環境
fusion_place のサーバ上でなくとも、fusion_place サーバに URL でアクセスできるコンピュータ上 [1] であれば、[Web API] を介して fusion_place サーバでの処理を実行することができます。
| [Web API] では、セッション情報のやり取りに Cookie を使いますので、クライアント側は Cookie を受け入れ可能でなければなりません。 |
Web API の呼び出し方法
[Web API] を使うには、fusion_place の API 用 URL に、XML 形式テキストデータとして、リクエスト内容を POST します。そうすると、依頼された処理をサーバが実行し、処理結果（レスポンス）が同じく XML 形式テキストデータとして返されます。
API 用 URL
fusion_place のサーバの URL の末尾に、/api/1.2/requests を追加したものが、API 用の URL です。例えば fusion_place のサーバの URL が、http://localhost:50000/fusionplace ならば、API 用 URL は以下の通りです。
認証
WWW-Authenticate: Digest realm="FusionPlace System",qop="auth",nonce="978cfd86321e50711213062f4573b9e7"
fusion_place サーバは、ダイジェストアクセス方式の認証（RFC2617）を行います。したがって、[Web API] を使用して fusion_place サーバに処理を依頼するクライアントプログラムは、ダイジェストアクセス方式の認証に対応している必要があります。多くのプログラム言語で、ダイジェストアクセス方式に容易に対応できるようなライブラリが提供されています。
ダイジェストアクセス方式では、ユーザ管理の範囲を表すために「レルム（Realm）」を用います。fusion_place のレルムは FusionPlace System です。
なお、[Web API] は、fusion_place 使用権許諾契約書で定義される「クライアントプログラム」のひとつです。従って、ひとつのユーザアカウントを用いてひとつのクライアントプログラムで運用できるセッション（ログイン以降ログアウトまたはクライアントプログラム終了までの業務）の数はひとつに限られるという、使用権許諾契約約款又は利用規約中の規定は、[Web API] にも適用されます。
HTTP メソッド
HTTP メソッド（HTTP プロトコルを用いてサーバに処理やデータを依頼する際の命令文）には、GET, PUT, POST などがありますが、fusion_place の [Web API] では、必ず、POST を用いて下さい。
HTTP リクエスト（通常のリクエスト）
リクエストヘッダ
必要に応じて以下の HTTP ヘッダを設定して下さい。
| HTTP ヘッダ | 必須 | 説明 |
|---|---|---|
Content-Type |
No |
指定する場合、 |
Content-Encoding |
No |
指定する場合、 |
Accept-Encoding |
No |
指定する場合、 |
Accept-Language |
No |
レスポンスの言語。日本語なら 上記ルールで決まる言語が、日本語、英語以外ならば、英語に置換されます。 |
Accept-Charset |
No |
レスポンスに適用する文字集合。2 つ以上指定した場合、2 つ目以降は無視されます。指定しなければ、 |
リクエストボディ
リクエストボディの内容は以下のようなテキストデータです。
<?xml version="1.0" encoding="Windows-31J"?> (1)
<request type="IMPORT_VALUES" desc="実績インポートA"> (2)
<!-- ... -->
</request> (3)| 1 | XML 宣言 |
| 2 | 「リクエスト」開始 |
| 3 | 「リクエスト」終了 |
リクエスタを使用する場合のリクエストファイルの記述形式と似ていますが、以下の違いがあります。
-
リクエスタの場合は、ひとつのリクエストファイルのの中に複数のリクエストを含めることができますが、[Web API] では、一回の HTTP リクエストに含めることができるリクエスト（
requestタグで囲まれた範囲）はひとつに限られます。また、そのため、[Web API] では全体を囲むresuestsタグは使用されません。 -
リクエスタで使用できる 環境変数値の埋め込み および エクスターナルモード は、[Web API] では使用できません。
上記の相違点を除いて、リクエスタを使用する場合のリクエストファイルとまったく同様に記述して下さい。
HTTP リクエスト（セッション確立用のリクエスト）
リクエスト送信に先立って、認証を済ませ、セッションを確立したい場合があります。このようなニーズが生じるのは、典型的には、HTTP/1.1 で導入された「Chunked transfer encoding （CTE）」を用いてデータ送信したい場合です。
CTE を適用すると、送信するデータの長さを HTTP ヘッダ（Content-Length）に設定する必要がないため長大なデータを送信するのに便利ですが、一部のクライアントは、CTE を適用した場合には認証に対応していません（例えば、Java のクライアントサイド API である HttpUrlConnection）。
そのような場合、ここでご説明するリクエストボディを含むリクエストを CTE を適用しないで送信し、その後、CTE を適用して通常のリクエストを送信します。そのようにすると最初のリクエスト送信時に認証が行われますので、後続の CTE でのリクエスト送信時は認証を回避することができます。
HTTP レスポンス
HTTP ステータスコード
処理結果に応じて、標準に即した HTTP レスポンスコードが返されます。例えば、サーバとの通信に支障が無かった場合、レスポンスコードとして 200 OK が返されます。200 OK の意味に注意して下さい。これはサーバとの通信に関して支障が無かったことを示しているだけであり、サーバ側でエラーや警告なくリクエストを処理できたことを意味するものではありません。リクエストの処理に成功したかどうかを知るには、レスポンスボディ中の「処理結果コード」を検査する必要があります。
レスポンスボディ
セッション確立用のリクエストに対するレスポンスの場合、レスポンスボディはありません。
通常のリクエストに対するレスポンスボディの内容は以下のようなテキストデータです。
<?xml version="1.0" encoding="Windows-31J"?> (1)
<response type="IMPORT_VALUES" desc="実績インポートA"> (2)
<!-- ... -->
</response> (3)| 1 | XML 宣言 |
| 2 | 「レスポンス」開始 |
| 3 | 「レスポンス」終了 |
リクエストボディの場合と同様に、一回の HTTP レスポンスに含まれるレスポンス（response タグで囲まれた範囲）はひとつだけです。そのため、[Web API] では全体を囲む responses タグは使用されません。
上記の相違点を除いて、 リクエスタを使用した場合のレスポンスファイル とまったく同じ規則が適用されます。