RESTful Web APIs 読書メモ(3)

Chapter 3. Resources and Representations

  • RESTは、プロトコルでもファイルフォーマットでもフレームワークでもない。
  • RESTは設計制約のセット
    • ステートレス
    • HATEOAS
    • などなど

  • HTTP, URI, HTMLを理解することは、REST制約を理解するための鍵となる

    • HTTP, URI, HTMLの根底には、リソース、表現という概念がひそんでいる
    • Clientにとって、Resourceがなにであるかは重要ではない。ClientはURLと結果の表現だけを見ているから
    • 表現とは、有益な形にリソースを加工したドキュメントであり、リソースの現在の状態をクライアントで読み取れるようにしたもの

*GET * 表現の問い合わせ * POST, PUT, PATCH * 表現の提案

  • リソースは一つ以上の表現をもつ

    • 言語(en, ja,…)
    • フォーマット(JSON, XML,…)
    • 要約と全文

  • クライアントからは、

    • content negotiation
    • 一つのURLに複数のURI

プロトコルセマンティクス

  • リクエストメソッド

    • GET
      • リソース表現を取得
      • 安全でかつ冪等
      • リソースの状態変更を期待する場面では使うべきでない
      • よく使われるレスポンスコードは200(OK) or 301(Moved permanently)
      • リソースがない場合、404(Not found)
      • リソースが削除(DELETE)されていた場合、410(Gone)
    • DELETE
      • リソースを破棄
      • 安全ではないが冪等
      • よく使われるレスポンスコードは204(No content), 200(OK), 202(Accepted: 後で削除)
    • POST(to append)
      • 指定された表現でリソースを新規作成
      • 追記の場合のレスポンスコードは201(Created)
      • 201は作成されたリソースのURIを示すLocationヘッダをもつ
      • 作成はするがまだ完了していない場合、202(Accepted)が返される
      • 安全でもなく冪等でもない
    • POST(overload)
      • PUT, DELETEの代わりに投げつける
    • PUT
      • リソースを置き換える
      • GETで取得し、修正してPUTで投げる
      • リクエスト内容に不備があれば、サーバーは拒否する自由がある
      • 返されるステータスコードは、200(OK), 204(No content)
      • 冪等である
      • 既知のURLに新しいリソースを作成するためにも用いられる
      • 新規リソースを作成する場合でさえ冪等
    • HEAD
      • リソースのヘッダレスポンスのみ返す
    • OPTIONS
      • 利用できるhttpメソッドの列挙
    • CONNECT, TRACE
      • プロキシのためのもの

  • RFC-5789

    • PATCH
      • 指定された表現に基づいてリソースの一部を修正する
      • PUTとは異なり微調整が可能
      • リクエストも変更対象の差分だけを送ることが可能
      • 変更後のリソースをクライアントに戻す場合、200(OK)を返す
      • 成功を伝えるだけであれば、304(No Content)を返す

  • 標準候補だった(RFC2068で入り、2616で破棄)

    • LINK
      • 別のリソースとリンクを張る
      • 安全ではないが冪等
      • URLはLINKヘッダで指定
    • UNLINK
      • 別のリソースとのリンクを破棄する
      • 安全ではないが冪等
      • URLはLINKヘッダで指定

  • WebDAV(RFC4918)

    • COPY, MOVE, LOCKなど7つのメソッドを追加

  • RESTful system

    • 独立したコンポーネント(サーバー、クライアント、キャッシュ、プロキシ)で構成されている
    • HTTPのプロトコルセマンティクスの大半はHTTPメソッドとして定義されている
    • APIをhtmlで記述する場合、メソッドはGET, POSTに制限される
    • ファイルシステムGUIアプリなら、HTTP+WebDAVのメソッドが使われるだろう
    • キャッシュやプロキシならPATCHメソッドの使用が考えられる

つづき・・・

RESTful Web APIs 読書メモ(4)

rest