ASP.Net Web APIを始める前に
Restとは
- REpresentational State Transfer
- Restとは2000年にRoy Fielding氏が提唱
- Restの設計原則
- セッションなどの状態管理を行わない。
- WebシステムではHTTPにセッション管理はない。
- セッションなどの状態管理を行わない。
- 情報を操作する命令の体系があらかじめ定義・共有されている。
- WebシステムではGET、POSTなど
- すべての情報は汎用的な構文で一意に識別される。
- URL、URI
- 情報内部に別の情報や状態へのリンクを含めることができる。
- ハイパーメディア
Restにおけるリソース
リソース
- URLはリソースの名前を表す。
処理内容 リソースの名前 リソース 商品データを全て取得する。 ~/***/Items 商品データ全て IDと一致する商品データを取得する。 ~/***/Items/{id} idと一致する商品データ 商品データを追加する。 ~/***/items 商品データ全て IDと一致する商品データを更新する。 ~/***/Items/{id} idと一致する商品データ IDと一致する商品データを削除する。 ~/***/Items/{id} idと一致する商品データ - HTTPメソッドは動詞、URLは名詞
※すべての商品データ「^/***/Items」を取得「Get」する。
※名詞、動詞に該当しない場合はクエリ文字列またはBodyやヘッダなどで表す。
- HTTPメソッドは動詞、URLは名詞
リソースの設計指針
- URIにプログラミング依存の拡張子を利用しない。
- URIに実装依存のパス名を利用しない。
- URIにプログラミング言語のメソッド名を使用しない
- URIにセッションIDを含めない。
- URIはそのリソースを表現する名詞である。
クールURI
- 良いURIやきれいなURIをクールURIと呼びます。
- 言葉の起源は、Webの発明者 Tim Berners-Lee が1998年に発表した「Cool URIs don’t change」(クールなURIは変わらない)
- 覚えやすく、開発者ではない普通の人にも使いやすい。
- Tim Berners-Lee の言葉「URIは変わらないべきである。変わらないURIこそが最上のURIである」
※寿命が長いURI(リンク切れにならない)
HTTP 1.1
- メソッドはGET、POST、PUT、DELETE、HEAD、OPTION、TRACE、CONNECTの8つです。
HTTPメソッド
- HTTPメソッドはリソースをどのように操作したいかを表す。
メソッド 意味 べき等性 GET リソースの取得 べき等 POST 子リソースの作成、リソースへのデータの追加、そのほかの処理 べき等ではない PUT リソースの更新、※リソースの作成 べき等 DELETE リソースの削除 べき等 HEAD リソースのヘッダ(メタデータ)の取得 OPTOINS リソースがサポートしているメソッドの取得 TRACE 自分宛にリクエストメッセージを返す(ループバック)試験 CONNECT プロキシ動作のトンネル接続への変更
CRUD 意味 メソッド Create 作成 POST/PUT Read 読み込み GET Update 更新 PUT Delete 削除 DELETE
べき等性
- べき等とはある操作を何度行っても同じ結果になる場合、この操作はべき等と言う。
メソッド べき等性 GET べき等 URIに対して何度GETを繰り返してもリソースの状態は変化しない事が保証されている。 POSE べき等ではない PUT べき等 DELETE べき等 一度削除しても、複数回削除しても、削除された状態が変わる事はありません。
HTTPメソッドの選択
- HTTPメソッドの選択
メソッド 処理内容 GET 商品データを全て取得する。IDと一致する商品データを取得する。 POST 商品データを追加する。 PUT IDと一致する商品データを更新する。 DELETE IDと一致する商品データを削除する。
Getメソッド
- URLの末尾に「?」をつけ、「パラメータ名="値"」という形式でデータを送信する。
- パラメータ
- 「?」はパラメータの始まりです。
- 「&」はパラメータの区切りです。
- 「=」の左側が変数名、右側が値です。
POSTとPUTの使い分け
- PUTを選択する場合
- クライアント側でURLが決められる場合
- 商品IDなどのIDが外部システムなどで決定される場合、
リソース(URL:~/***/Items/{id})が変化しないのでべき等です。
2回目以降は上書きまたは処理を行わないのでリソースに変化がありません。
- POSTを選択する場合
- クライアント側でURLが決められない場合
- 商品IDなどのIDを自動付与するシステムでは作成の度にIDが変わります。
リソース(URL:~/***/Items/{id})が変化するのでべき等ではありません。
POSTを選択するのが適当と言えます。
※リソースの作成はPOSTが好ましい。PUTはクライアントとサーバが密結合となる為です。
POSTとGETの使い分け
- 以下の場合はPOSTを使います。
- 大量のデータを送信したい場合に使用します。
※Internet ExplorerではGetメソッドで処理できるURLの長さに制限があります。
データ量が多いときはPOSTを使用します。 - サーバーでデータ更新をする場合に使用します。
- 秘匿情報を送る場合に使用します。
※外部に知られたくない情報を送る場合に使用します。
- 大量のデータを送信したい場合に使用します。
HTMLのフォーム
- HTMLのフォームはGETとPOST以外は利用できません。
- Ajaxの発展により解消しつつある。
XMLHttpRequestが任意のメソッドを利用できる為です。 - プロキシサーバでGETとPOST以外のアクセスを制限している場合があります。
- 他のPUTやDELETEを利用する方法
- _methodパラメータ (Ruby on Railsが採用している)
- フォームの隠しパラメータ(hidden)に_methodというパラメータを用意し、送りたいメソッドの名前を入れます。
- <form method=“POST” action=“/list/item1”>
- <input type=“hidden” id=“_method” name=“_method” value=“PUT” />
- </form/>
- フォームの隠しパラメータ(hidden)に_methodというパラメータを用意し、送りたいメソッドの名前を入れます。
- X-HTTP-Method-Overrideヘッダを利用する。
- _methodパラメータ (Ruby on Railsが採用している)
- Internet ExplorerではURLに最大2,083文字が使用可能
- Microsoft Internet Explorer では、URL (Uniform Resource Locator) に使用できる最大文字数は 2,083 文字です。また、Internet Explorer のパスに使用できる最大文字数は 2,048 文字です。この制限は、POST 要求と GET 要求両方の URL に適用されます。
- GET メソッドを使用する場合、最大文字数は 2,048 文字から実際のパスの文字数を減算した文字数に制限されます。
- ただし、POST メソッドでは、名前と値の組み合わせの発行については URL の文字数が制限されません。これらの組み合わせは URL ではなく、ヘッダーで送信されるためです。
- RFC 2616, "Hypertext Transfer Protocol -- HTTP/1.1," では、URL の長さに関する要件は取り決められていません。
- https://support.microsoft.com/ja-jp/kb/208427
ステータスコードの分類
- 1xx
- 処理が継続している事を示す。
- 2xx
- リクエストが成功した事を示す。
- 3xx
- 他のリソースへのリダイレクトを示す。
- 4xx
- クライアントのエラーを示す。
- 5xx
- サーバエラーを示す。
よく使うステータスコード
コード | 意味 |
200 | リクエスト成功 |
201 | リソースの作成 |
204 | リクエスト成功、返すリソースがない |
301 | リソースの恒久的な移動 |
303 | 別URLの参照 |
400 | リクエストの間違い |
401 | アクセス権不正 |
404 | リソースの不在 |
500 | サーバ内部エラー |
503 | サービス停止 |
ステータスコードの利用例
事例 | ステータス | Body |
在庫データの取得・削除 | 200 OK | 対象データが格納される |
在庫データの更新 | 空 | |
在庫データの追加 | 201 Created | 追加した在庫データが格納される (POSTの場合、ヘッダのLocationには、追加した在庫データを表すURLが格納される) |
204 | ||
301 | ||
303 | ||
リクエスト検証エラー | 400 Bad Request | 検証エラー情報が格納される |
401 | ||
同時実行制御エラーの発生 | 404 Not Found | 空 |
例外の発生 | 500 Internal Server Error | エラー情報が格納される |
503 |