こんにちは、Karesansui Projectで開発をやってます船ヶ山です。
「開発メンバーがおくるKaresansui技術解説の第2回」は、KaresansuiとRESTfulについての説明をしたいと思います。
「開発メンバーがおくるKaresansui技術解説の第2回」は、KaresansuiとRESTfulについての説明をしたいと思います。
■概要
ご存じのようにRESTfulは、以下の定義がなされたアーキテクチャスタイルですがKaresansuiも同じように定義し設計、実装されています。
など
■HTTPリクエストについて
karesansuiでは、GET、POST、PUT、DELETEのHTTPリクエストを利用しサーバーと通信しています。
また、karesansuiではオーバーライドポストに対応しており、POSTデータに"_method=PUT"のようなパラメタを付加することでPOSTメソッドをPUT処理することが可能になっています。
_methodの例
<input type="hidden" name="_method" value="PUT" />
補足
Karesansuiの画面右上に点滅する3つのランプがありますが、こちらはサーバーとHTTPリクエスト中の場合に点滅するようになっています。
■HTTPレスポンスコードについて
Karesansuiでは多種多様なHTTPレスポンスコードが返ってきます。
補足 : 普段、ブラウザでWebページを見るときは意識する機会は少ないと思いますが、レスポンスコードはブラウザや各種Webクライアント、サービスにとって不可欠なものです。
ここでは、Karesansuiが返してくる主なレスポンスコードについて紹介します。
* 2xx : 処理が成功したことを伝えるコードです。
200 : OK
GETリクエストを送信したとき、指定したリソースが存在すればそのHTMLとともにこのコードを返します。正常にリクエストを処理したことを伝えるコードです。
202 : Accepted
時間のかかる処理をサーバが正常に受け入れたときに返ってくるコードです。
Karesansuiでは、ジョブマネージャ(Pysilhouette)にjobが登録された際にこのコードが返ってきます。
* 3xx : リダイレクトさせるコードです。
303 : See Other
新規にリソースを作成したとき、そのリソースのHTMLを取得させるために返すコードです。
DELETEしてリソースがなくなった際にも、有効なURIへリダイレクトさせるために返ってきます。
* 4xx : クライアント側のエラーを伝えるコードです。
400 : Bad Request
送信したパラメータが不正だったときに返ってくるコードです。ゲスト作成などの際に送信したパラメータが、サーバ側のバリデートで弾かれたときに返ってきます。
401 : Unauthorized
認証に失敗した際に返ってくるコードです。 KaresansuiではBasic認証を使っています。(KaresansuiはSSLで動作させることが可能です)
404 : Not Found
リソースがないことを表すコードです。このコードは普段でも見かけることがあると思います。
409 : Conflict
作成しようとしたリソースと同じものがあったときに返ってくるコードです。ユーザのログイン名など、重複が許されないリソースの作成・編集で返ってくることがあります
* 5xx : サーバ側のエラーを伝えるコードです。
500 : Internal Server Error
サーバ内部のエラーを伝えるコードです。このコードを受け取ったとき、Karesansuiの画面の右上や通知部分にメッセージが表示されます。
Karesansuiのバグが発生している状況ですので、見かけたらぜひご報告ください。
■.part + standaloneについて
Karesansuiでは、RESTの表現として HTML、JSONに加えて、PARTという表現(xxx.json xxx.xml xxx.html xxx.partを指します)を用いています。
PARTは、Karesansuiオリジナルの表現で、AjaxでよみこまれるHTMLの一部をあらわす表現です。
Ajaxで読み込まれるHTMLの一部は、HTMLの一部であって、HTMLではありません。
そのようなファイルを表現するために、Ajaxで読み込まれるHTMLの一部 = part という意味で作成しました。
加えて、standaloneというURIクエリをもち、以下の形式で、HTMLとして表示できるような仕掛けも用意しています。
例) http://{ホスト名}/karesansui/v1/host/{ホストID}/guest/{ゲストID}/snapshot.part?standalone=1
ご存じのようにRESTfulは、以下の定義がなされたアーキテクチャスタイルですがKaresansuiも同じように定義し設計、実装されています。
- ステートレスなアクセス
- 一意なリソースを定義
- リソースは一意なアドレス(URI)を持つ
- 一つのリソースは複数のアドレスを持つ
など
■HTTPリクエストについて
karesansuiでは、GET、POST、PUT、DELETEのHTTPリクエストを利用しサーバーと通信しています。
また、karesansuiではオーバーライドポストに対応しており、POSTデータに"_method=PUT"のようなパラメタを付加することでPOSTメソッドをPUT処理することが可能になっています。
_methodの例
<input type="hidden" name="_method" value="PUT" />
補足
Karesansuiの画面右上に点滅する3つのランプがありますが、こちらはサーバーとHTTPリクエスト中の場合に点滅するようになっています。
■HTTPレスポンスコードについて
Karesansuiでは多種多様なHTTPレスポンスコードが返ってきます。
補足 : 普段、ブラウザでWebページを見るときは意識する機会は少ないと思いますが、レスポンスコードはブラウザや各種Webクライアント、サービスにとって不可欠なものです。
ここでは、Karesansuiが返してくる主なレスポンスコードについて紹介します。
* 2xx : 処理が成功したことを伝えるコードです。
200 : OK
GETリクエストを送信したとき、指定したリソースが存在すればそのHTMLとともにこのコードを返します。正常にリクエストを処理したことを伝えるコードです。
202 : Accepted
時間のかかる処理をサーバが正常に受け入れたときに返ってくるコードです。
Karesansuiでは、ジョブマネージャ(Pysilhouette)にjobが登録された際にこのコードが返ってきます。
* 3xx : リダイレクトさせるコードです。
303 : See Other
新規にリソースを作成したとき、そのリソースのHTMLを取得させるために返すコードです。
DELETEしてリソースがなくなった際にも、有効なURIへリダイレクトさせるために返ってきます。
* 4xx : クライアント側のエラーを伝えるコードです。
400 : Bad Request
送信したパラメータが不正だったときに返ってくるコードです。ゲスト作成などの際に送信したパラメータが、サーバ側のバリデートで弾かれたときに返ってきます。
401 : Unauthorized
認証に失敗した際に返ってくるコードです。 KaresansuiではBasic認証を使っています。(KaresansuiはSSLで動作させることが可能です)
404 : Not Found
リソースがないことを表すコードです。このコードは普段でも見かけることがあると思います。
409 : Conflict
作成しようとしたリソースと同じものがあったときに返ってくるコードです。ユーザのログイン名など、重複が許されないリソースの作成・編集で返ってくることがあります
* 5xx : サーバ側のエラーを伝えるコードです。
500 : Internal Server Error
サーバ内部のエラーを伝えるコードです。このコードを受け取ったとき、Karesansuiの画面の右上や通知部分にメッセージが表示されます。
Karesansuiのバグが発生している状況ですので、見かけたらぜひご報告ください。
■.part + standaloneについて
Karesansuiでは、RESTの表現として HTML、JSONに加えて、PARTという表現(xxx.json xxx.xml xxx.html xxx.partを指します)を用いています。
PARTは、Karesansuiオリジナルの表現で、AjaxでよみこまれるHTMLの一部をあらわす表現です。
Ajaxで読み込まれるHTMLの一部は、HTMLの一部であって、HTMLではありません。
そのようなファイルを表現するために、Ajaxで読み込まれるHTMLの一部 = part という意味で作成しました。
加えて、standaloneというURIクエリをもち、以下の形式で、HTMLとして表示できるような仕掛けも用意しています。
例) http://{ホスト名}/karesansui/v1/host/{ホストID}/guest/{ゲストID}/snapshot.part?standalone=1
Leave a comment