keyboard_arrow_leftsetBadgeNumber()get()keyboard_arrow_right

WebApi

モジュールパス: /alier_sys/WebApi.js

概要

WebApi クラスは alier の Web インターフェースを実現するための、クライアント側の通信処理を実装するクラスです。

ユーザはこの WebApi のインスタンスを生成し、各種のメソッドを呼び出すことでサーバとの通信を行うことができます。

解説

基本的な使い方

WebApi クラスは REST API に適合するよう設計されたクラスです。 HTTP メソッドに対応したインスタンスメソッドを呼び出すことで Web サーバへのリソースアクセスを実行します。

既定の実装ではリソースを JSON データで表現しています。詳しい通信方式については Web インターフェースを参照してください。

この例では、リソースのホストとパスを指定してインスタンスを作成し、get() メソッドを呼び出してリソースを取得します。

const webApi = new WebApi({ host: "https://example.com", path: "/hello/" });
const response = await webApi.get();

HTTP メソッド

このクラスでは

GET
POST
PUT
DELETE
HEAD
OPTIONS
PATCH

に対応するインスタンスメソッドが定義されています。

既定では、設定されたパラメタはまず、動的なパスの指定の通りにパスに含まれる変数ラベルの置換に使われ、次いでクエリパラメタやボディに割り当てられます。

返値は、レスポンスステータスによって既定のオブジェクトかボディをパースした結果となります。

HTTP 201 Created の場合:
```
{ created : true, status: 204 }
```
HTTP 204 No Content の場合:
```
{ noContent : true, status: 204 }
```
HTTP 304 Not Modified の場合:
```
{ notModified: true, status: 304 }
```
その他 HTTP 2xx / 3xx 系の応答の場合:

レスポンスボディに記述された JSON をパースした結果です。

既定の動作は makeRequest() と makeResponse() によって実装されています。これらのメソッドをオーバライドすることで既定の動作を変更することができます。

動的なパスの指定

アカウントごとのリソースなど path を動的に指定したい場合は、パスをパターンで指定することができます。

パターンはコロンとキーワードを組み合わせた変数ラベルによって表されます。例えば、パス /profile/:userId であれば :userId が変数ラベルにあたります。この場合、/profile/alice や /profile/bob はいずれも /profile/:userId に一致するパスと解釈されます。 /account/:userId/file/:fileId のように複数の変数ラベルにも対応しています。

パスの変数ラベルで表される部分は、対象の Web API に対するリクエストパラメタとして利用されます。各メソッドの引数に変数ラベルと対応したプロパティを与えると、その変数ラベルをプロパティで置換したパスに対してリソースアクセスを実行します。例えば、変数ラベルを含むパス /profile/:userId を持つインスタンスのメソッドの引数に { userId: "alice" } というオブジェクトを渡すと、リクエストの URL のパスは /profile/alice に置換されます。

const api = new WebApi({ host: "https://api.example.com", path: "/profile/:userId" });
const result = await api.get({ userId: "alice" });
// => https://api.example.com/profile/alice

変数ラベルへの置換後、残りのプロパティは各メソッドの引数としてクエリやボディに割り当てられます。

詳しくは Pattern クラスを参照してください。

サーバ側の `WebApi` との関係

サーバ側にも WebApi クラスが用意されています。

サーバ側の WebApi はクライアント側の WebApi のカウンタパートとなっています。クライアント側のメソッドを呼び出すとサーバ側の対応したメソッドが呼び出されるようになっています。サーバ側のメソッド呼び出しの返値はクライアント側での対応するメソッドの返値となります。

Web 認証の対応

Web 認証を要求する API のための関数として、makeAuthorizedRequest() および shouldRetryOnUnauthorized() 関数が定義されています。

これらの関数は、コンストラクタ引数として認証処理の実装を提供する AuthAgent が渡されている場合に利用されます。

makeAuthorizedRequest() は次のことを行います:

AuthAgent から認証情報を取得します。
(1.) の認証情報を makeRequest() が返すオブジェクトに追記します。

shouldRetryOnUnauthorized() は HTTP 401 Unauthorized 応答が返却されると呼び出されます。この関数は２つの働きがあります:

401 応答に対して認証情報の更新を試みます
401 応答に対してリクエストを再送できるかどうかを判定します

前者 (1.) については AuthAgent::refresh() 関数によって行われます。

後者 (2.) は (1.) の結果によって決まります。shouldRetryOnUnauthorized() の結果、再送可能と判定された場合、makeAuthorizedRequest() が再び呼び出され、その結果がリクエストとして送信されます。

一度のリクエストに対して shouldRetryOnUnauthorized() が複数回呼び出されることはなく、再送されたリクエストが失敗した場合、WebApi はその結果をレスポンスとして返します。

コンストラクタ

構文

new WebApi({ host, path }) => WebApi
new WebApi({ host, path, authAgent }) => WebApi

引数

引数は以下のプロパティを持つオブジェクトリテラルです。

host: string

サーバのホスト名（オリジン）を表す文字列です。この値はプロパティ host に反映されます。
path: string

サーバ上の API を表すパス文字列です。この値はプロパティ path に反映されます。

非 ASCII 文字や URL の構文上特殊な意味を持つ文字を値に含む場合、それぞれの値は URL に含めることのできる文字列に置換されます。
authAgent: AuthAgent （省略可）

省略可能な認証処理を制御するオブジェクトです。省略した場合、その Web API に対してチャレンジレスポンスを利用した認証は行われません。

例えば、認証を要求しない公開の Web API や、Cookie を利用した認証を利用する場合などに対しては引数 authAgent は必須ではありません。

このオブジェクトは makeAuthorizedRequest() および shouldRetryOnUnauthorized() で利用されます。makeAuthorizedRequest() では認証トークンを Authorization ヘッダとして追加するために利用します。shouldRetryOnUnauthorized() では、認証エラー時に無効な認証トークンを更新するために利用します。