RESTful Web APIs 読書メモ(7)

Chapter 7. Pure hypermedia Design

  • コレクションパターンは強力であるが、何でもかんでも使えるではない

  • MAZE+xmlのコレクションパターンでの表現（5章）

    • どう見ても迷路ゲームのアプリケーションセマンティクスにマッチしていない

  • APIの設計方針として、汎用的なハイパーメディアを用いることができる

HTML

  • 多くのOS標準搭載されたブラウザにレンダリングさせてデバッグできる
  • XMLやJSONよりも、よりドキュメントとしての構造を強いている
  • 標準化されたハイパーメディアコントロールを有している
    • formタグ(method="GET" = outbound link
      • inputタグによるURIテンプレート代替
    • formタグ(method="POST" = リソース生成依頼
    • linkタグ(rel="stylesheet") = embedded link
    • linkタグ(rel="self") = outbound link
    • aタグ = outbound link
    • imgタグ、scriptタグ = embedded link
    • 特別な問題領域に特化したものではない

  • 解析 / 生成のためのツールが多くある

  • データ構造としてのHTML

    • ol = JSON順序リスト
    • ul = JSON非順序リスト
    • dl = JSONオブジェクト
    • table = 二次元配列
    • div/span = グループ化

  • 汎用属性

    • rel
      • IANAに登録されたリレーションを用いることで、HTMLにアプリケーションセマンティクスを組み込める
    • id
      • 文書内で一意の識別子
      • idでアプリケーションセマンティクスをフックするのはオススメではない
        • 複数の文書をマージしたい場合に一意性が保証出来ないため
    • class
      • 最も柔軟性のある属性
      • wwwではcssによるフォーマッティングに用いられる
      • アプリケーションセマンティクスとしては、グループ化のタグとして用いることができる

microformat

  • htmlにアプリケーションセマンティクスを付与する技術
  • classとrel属性に与える値のみを定義する
  • html + microformatでドメイン特化なフォーマットを再現できる
  • hCard
    • グループ化やフィールドのためのclassのみが定義されている
    • hCard自身はハイパーメディアコントロールではないが、htmlから拝借して、connectednessを実現できる
    • どのhtmlタグに付けるかは自由
    • vCard(RFC6350)を元にしている
      • ハイパーメディアコントロールではない

Microdata

  • html5用、microformat改良版
  • 総本山はschema.org
  • microformstにおけるclassの置き換え
  • リレーションは定義出来ない
  • class属性は本来、アプリケーションセマンティクスを体現する場ではない
  • プロパティ
    • itemprop
      • グループ名、フィールド名の定義
    • itemscope
      • Microdataによる表現を開始するタグに付与
    • itemtype
      • 付与したタグをハイパーメディアコントロールにする
      • 値はURL
    • itemid
    • itemref

フォームにアプリケーションセマンティクスを加えること

  • リンクリレーションは、リソース間の関連を記述するもの

    • 自身と同じURLに異なるリンクリレーションのリンクを貼る => リソース状態が変更されることを意味する
    • リンクはGETリクエストの発行となるため、HTTPメソッドの制約に反する

  • HTMLフォームなら、POSTリクエストを発行できる

    • リソース状態を変更することは制約に反しない
    • inputタグのclass属性にアプリケーションセマンティクスとなる用語を与える
    • アクションURLを組み立てるためのテンプレートは不要
      • formタグがアクションURLを持つため
    • sublitタイプのinputタグを置いて初めて、状態遷移が可能となる
      • 遷移させたくなければ、sublitを置く必要はない

  • リソース指向アプローチ

    • リソースを識別し、そこにハイパーメディアを試みる作り
    • まずリソースを識別することに重きを置いている

  • ハイパーメディア設計

    • リソースを識別することよりも状態遷移を識別することの方が重要

HTMLの限界

  • 本来のHTMLは、ハイパーメディアフォーマットなどではなく、human-readableに特化した標準
  • 全てのhttpプロトコルを実現できない
    • PUT, DELETEはJavascriptの手助けが必要
  • formで構成できるリクエストは、application/x-www-form-urlencodedか、multipart/form-dataのいずれか
  • 文字列と数字を区別しない
    • そのアプリケーションセマンティクスはhtmlの外で定義するしかない
  • 日付表現を定義していない
    • vCardのbdayはISO8601として個別に定義

html5

  • timeタグ
    • 特定のフォーマットでdate型やtimestamp型を表現
  • meterタグ
    • 特定の範囲内の測定値を表現
  • audioタグ
  • videoタグ
  • sourceタグ
  • embedタグ
  • inputタグのvalidation
    • 値としてdate, number, urlを表現
    • required属性で必須入力
    • クライアントサイドバリデーション
  • formタグ
    • texp/plainメディアタイプのサポート
  • Microdata
    • classs属性への意味づけ
  • PUT, DELETEは引き続き未サポート

Hypermedia Application Language (HAL)

  • media-type
    • application/hal+xml
    • application/hal+json
  • 要素としてresourceとlinkタグのみを定義されている
  • resourceタグ
    • httpリソースの表現
  • link
    • これ一つであらゆるハイパーメディアを扱える
      • GET, POST, PUT, DELETE, UNLINK
      • プロトコルセマンティクスを指定するすべはない
      • リレーションの意味を明示的にドキュメントとして残すしかない

Siren

  • JSONベースのハイパーメディアフォーマット
  • HTMLとCollection+JSONの合いの子のような立ち位置
  • entities
    • データをグループ化
    • htmlのdivタグ相当
    • URLを付与することでサブリソースとして振舞わせられる
    • links
      • 別のリソースへのリンク先を記述

Semantics Challenge

  • httpプロトコルセマンティクス
    • リソースにGET, POSTなどのリクエストメソッドを割り当てる
  • ハイパーメディア
    • サーバーで次に行わせたいリクエストを伝える仕組み
  • アプリケーションセマンティクス
    • アプリケーション状態やリソース状態をハイパーメディアで制御すること
  • ドメイン特化フォーマット
    • 例: Maze+XML
    • プロトコルセマンティクスを定義
    • アプリケーションセマンティクスも定義
    • 稀な存在
  • 標準フォーマット
    • Collection+JSON, AtomPubなど
    • プロトコルセマンティクス詳細に定義している
      • item-typeリソース = PUTに応答
    • アプリケーションセマンティクスは未定義
  • microformat
    • アプリケーションセマンティクスを定義
    • プロトコルセマンティクスは未定義
  • HTML, HAL, Siren
    • プロトコルセマンティクスを定義
    • アプリケーションセマンティクスも定義

つづき・・・

RESTful Web APIs 読書メモ(8)

rest