ASP.Net Web APIを始める前に

Restとは


  • REpresentational State Transfer
  • Restとは2000年にRoy Fielding氏が提唱
  • Restの設計原則
    • セッションなどの状態管理を行わない。
      • WebシステムではHTTPにセッション管理はない。
  • 情報を操作する命令の体系があらかじめ定義・共有されている。
    • WebシステムではGET、POSTなど
  • すべての情報は汎用的な構文で一意に識別される。
  • 情報内部に別の情報や状態へのリンクを含めることができる。
    • ハイパーメディア

 

Restにおけるリソース


  • リソースとは、WEB上の情報である
  • 世界中の無数のリソースは、それぞれURIで一意の名前を持つ
  • URIを用いることで、プログラムはリソースが表現する情報にアクセスできる。

 

リソース


  • URLはリソースの名前を表す。
    処理内容 リソースの名前 リソース
    商品データを全て取得する。 ~/***/Items 商品データ全て
    IDと一致する商品データを取得する。 ~/***/Items/{id} idと一致する商品データ
    商品データを追加する。 ~/***/items 商品データ全て
    IDと一致する商品データを更新する。 ~/***/Items/{id} idと一致する商品データ
    IDと一致する商品データを削除する。 ~/***/Items/{id} idと一致する商品データ
    • HTTPメソッドは動詞、URLは名詞
      ※すべての商品データ「^/***/Items」を取得「Get」する。
      ※名詞、動詞に該当しない場合はクエリ文字列またはBodyやヘッダなどで表す。

 

リソースの設計指針


  • 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/>
    • X-HTTP-Method-Overrideヘッダを利用する。

 

Internet ExplorerのURL


  • 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