no versions found for ApplicationFrameworkReferences / Appendix/webinterface / en

Web インターフェース

標準仕様

alier が標準で実装している Web インターフェースは REST API をベースとしています。

REST API はアプリケーションが別のアプリケーションやサービスのリソースにアクセスするための表現方法の１つです。REST API そのものは Web 標準の HTTP で構成されており、HTTP 通信ができれば言語などの違いを超えてリソースにアクセスすることができます。

alier の Web インターフェースでは、どのリソースにアクセスするかを URI で表現し、行いたい操作を HTTP リクエストメソッドで表現します。

URI

Web インターフェースで使用される URI は大まかにホストとパスとクエリから構成されています。

ホスト

リソースを持つ Web サーバを示します。通常はスキーム https:// とドメイン example.com を組み合わせた https://example.com となります。

パス

リソースを識別するためのパスです。ファイルパスと同じように /path/to/resource/ となっており、たいていは階層的な構造となっています。

クエリ

追加の操作を要求するためのパラメータです。

クエリは ? に続くキーと値のペアのリストで構成されています。 それぞれのペアは & で区切られ、キーと値は = で結合されます。

例

以下の URI をホストとパスとクエリに分解します。

https://example.com/path/to/resource/?key=value&foo=bar
  • ホスト: https://example.com
  • パス: /path/to/resource/
  • クエリ: ?key=value&foo=bar

HTTP リクエストメソッド

HTTP リクエストメソッドによってリソース操作を表現しています。また、やり取りされるリソースは JSON 文字列で表現してます。

HTTP リクエストメソッドのうち、リソースの取得や操作を行うためメソッドである GET、POST、PUT、DELETE を中心に説明していきます。

GET

GET メソッドはリソースの取得をリクエストします。取得に成功した場合は、ステータスコード 200 でリソースを取得できます。リソースは JSON 文字列で表現されています。

https://example.com/api/ のリソースを取得する HTTP リクエストは以下のようになります。

GET /api/ HTTP/1.1
Host: example.com

このときのレスポンスは以下のようになります。

HTTP/1.1 200 OK
content-type: application/json

{"John":"foo","Ann":"bar"}

パラメータを追加したい場合はクエリを利用します。

上記の例から John のみを取得するようにクエリで指定します。

GET /api/?target=John HTTP/1.1
Host: example.com

レスポンスは以下のようになります。

HTTP/1.1 200 OK
content-type: application/json

{"John":"foo"}

POST

POST メソッドはリソースの送信によってサーバ上の状態を変更します。リクエストのボディは JSON 文字列で表現します。リクエストが成功すると、新しいリソースが作成された場合はステータスコード 201 が、それ以外の場合は 200 が設定されたレスポンスが返されます。レスポンスにボディが含まれる場合は JSON 文字列で表現されます。

例として、キーに指定した各値の末尾に与えた値を加える API だとします。レスポンスは更新された値が返されます。既存のキーを指定するリクエストは以下の通りです。

POST /api/ HTTP/1.1
Host: example.com
Content-Type: application/json

{"John":"post"}

更新された値がレスポンスとして返されたとします。

HTTP/1.1 200 OK
content-type: application/json

{"John":"foopost"}

新しいキーを指定したリクエストは以下の通りです。

POST /api/ HTTP/1.1
Host: example.com
Content-Type: application/json

{"Taro":"init"}

ステータスコード 201 のレスポンスが返されます。

HTTP/1.1 201 Created
content-type: application/json

{"Taro":"init"}

PUT

PUT メソッドはリソースの置き換えをリクエストします。リクエストのボディは JSON 文字列で表現します。リクエストが成功すると、新しいリソースが作成された場合はステータスコード 201 が、それ以外の場合は 200 または 204 が設定されたレスポンスが返されます。

例として、指定したキーを与えた値で置き換える API だとします。既存のキーを更新するリクエストを作成します。

PUT /api/ HTTP/1.1
Host: example.com
Content-Type: application/json

{"John":"put"}

値が更新されたのでステータスコード 200 が返されます。

HTTP/1.1 200 OK

新しいキーでリクエストを作成します。

PUT /api/ HTTP/1.1
Host: example.com
Content-Type: application/json

{"Taro":"newone"}

新しいリソースが作成されるのでステータスコード 201 が返されます。

HTTP/1.1 201 Created

DELETE

DELETE メソッドはリソースの削除をリクエストします。パラメータを追加したい場合はクエリに指定します。リクエストが成功すると、レスポンスに追加の情報がなければステータスコード 204 が、それ以外の場合は 200 が設定されたレスポンスが返されます。

例として、指定したキーを削除する API だとします。削除に成功したらそのキーが入ったレスポンスが返されます。

存在するキーを削除するリクエストを作成します。

DELETE /api/?target=John HTTP/1.1
Host: example.com

削除に成功したので削除したキーを含むレスポンスが返されます。

HTTP/1.1 200 OK
content-type: application/json

{"deleted":"John"}

存在しないキーを指定したリクエストを作成します。

DELETE /api/?target=Bob HTTP/1.1
Host: example.com

キーが存在しない場合はコンテンツなしのレスポンスが返されます。

HTTP/1.1 204 No Content
content-type: application/json

WebApi クラス

alier では、上記の Web インターフェースを実装した WebApi をクライアント側とサーバ側の両方で用意してます。

クライアント側とサーバ側は対になるように設計されています。

  • クライアント側で WebApi メソッドを呼び出すと、サーバ側の対応したメソッドが呼び出される
  • サーバ側の返値がクライアント側の返値となる

ただ、実装上の違いもあります。

  • クライアント側はそのままインスタンス化できるが、サーバ側は継承クラスで処理を実装する必要がある

例えば、単にあいさつを返す API を実装してみます。

サーバ側で GET メソッドを受け取って、{ greeting: "Hello!" } と返す API は次のようになります。

class MyGreeting extends WebApi {
    async get(params) {
        return { greeting: "Hello!" };
    }
}

const greeting = new MyGreeting({ path: "/greet" });

この API に対して GET メソッドを呼び出すと { greeting: "Hello!" } が返されます。

const greeting = new WebApi({ host: "example.com", path: "/greet" });
const result = await greeting.get();
// { greeting: "Hello!" }

既存の API に組み込むこともできますが、クライアント側とサーバ側を alier で合わせると直感的な呼び出しになります。さらに詳しい使い方はクライアント側の WebApi とサーバ側の WebApi を参照してください。