RESTful Web APIs 読書メモ(10)

Chapter 10. The HyperMedia Zoo (Part. 1)

  • ハイパーメディアフォーマットカタログ
    • ドメイン特化フォーマット
    • 純粋ハイパーメディアフォーマット

ドメイン特化フォーマット

  • 特別なドメインの問題を表現するためにデザインされたフォーマット
  • 特化されたアプリケーションセマンティクスが定義されている

Maze+XML

  • media-type: application/maze+xml
  • プロトコルセマンティクス
    • GETメソッドを使ったリンクによるナビゲーション
  • アプリケーションセマンティクス
    • 迷路ゲーム
  • 5章参照
  • カスタムリレーションを定義することで拡張可能
  • XFornを使って、安全でないプロトコルを扱うこともできる

Open Search

  • mediatype
    • application/opensearchdescription+xml
  • プロトコルセマンティクス
    • GETメソッドによる検索
  • アプリケーションセマンティクス
    • 検索クエリ
  • 6章参照
  • 検索フォームを表現する標準フォーマット
  • search リンクリレーションを定義
  • 検索結果の表現は定義されていない

Problem Detail Documents

  • media-type
    • application/api-problem+json
  • プロトコルセマンティクス
    • GETメソッドによるナビゲーション
  • アプリケーションセマンティクス
    • エラー報告
  • HTTPステータスコードに、JSONとして構造化したhuman-readableなテキストを加える
    • title (必須)
    • describedBy (必須)
      • human-readableな説明へのリンク
    • supportId (オプション)
      • 問題の詳細な例へのリンク
  • エンドユーザー向けの例外報告ではなく、管理者向けの内部URL

SVG

  • media-type
    • image/svg+xml
  • プロトコルセマンティクス
    • XLinkと同じ
  • アプリケーションセマンティクス
    • ベクター画像
  • 別の画像リソースをリンクとして含めることができる
    • aタグを使用
    • ハイパーメディアコントロールではない
    • XLinkの role プロパティとしての立ち位置
  • XFormを埋め込むことで、プロトコルセマンティクスを追加できる
  • html5のsvgタグで、インラインに埋め込むことができる

VoiceXML

  • media-type
    • application/voicexml+xml
  • プロトコルセマンティクス
    • GETメソッドによるナビゲーション
    • GET(安全)やPOST(安全でない)メソッドによる任意の状態遷移
  • アプリケーションセマンティクス
    • 会話
  • 電話間における、会話の通信フォーマット

GeoJSON

  • media-type
    • application/json
  • プロトコルセマンティクス
    • GETメソッドによる座標系のトランスクルージョン
  • アプリケーションセマンティクス
    • 地理的な特徴、及びそのコレクション
  • 地理的な特徴を表現するフォーマット
  • ユーザビリティに悪影響をもたらす欠陥フォーマット
  • ハイパーメディアコントロールをもたない
    • URLに見えるただの文字列の塊
  • 素のJSONと区別する術はない
    • 解決策は、profileを提供すること
    • そんなもん公式に提供されてないけどモナ！
    • # コレクションパターンフォーマット
  • itemリソース
    • GET, PUT, DELETメソッドに応答する
    • 構造化された表現にフォーカス
  • collectionリソース
    • GET, POST(append)メソッドに応答する
    • itemリソースへのリンクにフォーカス

Collection+JSON

  • media-type
    • application/collection+json
  • プロトコルセマンティクス
    • コレクションパターン(GET/POST/PUT/DELETE)
    • GETメソッドによる検索
  • アプリケーションセマンティクス
    • コレクションパターン(collection, item)
  • 6章参照
  • JSONによるAtomPub代替フォーマット

Atom Publishing Protocol

  • media-type *application/atom+xml
    • application/atomsvc+xml
    • application/atomcat+xml
  • プロトコルセマンティクス
    • コレクションパターン(GET/POST/PUT/DELETE)
    • 検索拡張(GET)
    • フォームナビゲーション拡張(GET)
  • アプリケーションセマンティクス
    • コレクションパターン(feed/entry)
      • feed
        • Blog投稿のセマンティクス
          • autor, title, category,…
      • entry
        • バイナリエントリ
          • 画像等
        • メタデータをもつAtomエントリ
  • RFC5023, RFC4287
  • 6章参照
  • RESTful APIの先駆け
  • Google API(GData)の基盤として用いられている

OData

  • media-type
    • application/json; odata=fullmetadata
    • application/json; odata=minimalmetadata
  • プロトコルセマンティクス
    • 修正コレクションパターン(GET/POST/PUT/DELETE/PATCH)
    • GETメソッドによるフィルタ、並び替え
    • GET(安全)、POST(安全でない)による任意の状態遷移
  • アプリケーションセマンティクス
    • コレクションパターン(feed/entry)
  • AtomPubベース
  • JSONオブジェクトのプロパティはsemantic descriptorとして機能する
  • odata. で始まるプロパティは、ハイパーメディアコントロール、またはメタデータ
    • odata.id
      • エントリリソースの一意的なID
        • たいていURI
    • hoge@odata.type
      • プロパティの型を示すメタデータ
    • odata.editLink
      • atomPubにおけるeditリレーションと同じ
    • hoge@odata.navigationLinkUrl
      • ほかのリソースへのハイパーメディアリンク
  • コレクションの暗黙的なフィルタと並び替えをサポート
    • フォームから明示的に指示するものではない
    • Urlで宣言的なルールを指示する
      • posts$filter=substringof('hoge',Content)
      • 複合条件の場合、+and+ で連結する
  • 状態遷移
    • function
      • GET(安全)な状態遷移
        • 暗黙的なフィルタを使用できない複雑なクエリに対して使用される
        • クライアントは、odata.metadataに示されるスキーマ記述言語(SDL)へのリンクをたどり、構築するクエリを学ぶ必要がある
    • action
      • POST(安全でない)状態遷移
  • メタデータの外だし
    • odata.metadataでSDLへのリンクだけを書き記す
      • 構造がシンプルになる
      • APIの修正と同時にSDLのメンテも必要
        • インピーダンスミスマッチを起こしやすい

純粋ハイパーメディアフォーマット

  • 自身がアプリケーションセマンティクスを持たない汎用フォーマット
  • プロトコルセマンティクスのみ持つ

HTML

  • media-type
    • application/xhtml+xml
  • プロトコルセマンティクス
    • GETメソッドによるナビゲーション
    • GET(安全)、POST(安全でない)メソッドによる任意の状態遷移
  • アプリケーションセマンティクス
    • ドキュメントに埋め込まれたhuman-readable表現
  • 7章参照
  • microdataやmicroformatsを直接埋め込むことができる
  • scriptタグで実行コードを埋め込むことができる
  • webブラウザで表示できるので、デバッグが容易

HAL

  • media-type
    • application/hal+json
    • application/hal+xml
  • プロトコルセマンティクス
    • リンクによる任意の状態遷移
    • httpメソッドを明示的に指定できない
    • human-readableなドキュメントに明記するのみ
  • アプリケーションセマンティクス
    • ない！
  • 7章参照

Siren

  • media-type
    • application/vnd.siren+json
  • プロトコルセマンティクス
    • GETメソッドによるナビゲーション
    • GET(安全)、POST/PUT/DELETE(安全でない)メソッドによる action をとおした任意の状態遷移
  • アプリケーションセマンティクス
    • あって無いようなもの
  • htmlのdivタグをjsonで書き下したentityを記述する
    • entity要素
      • classやpropertyのリストを持てる
      • htmlのaタグをのようなlinksのリストを持てる
      • htmlのformタグのようなactionsのリストを持てる
      • 子entryを持てる
  • 状態遷移図はHALとHTMLの中間

Link Header

  • media-type
    • なし(httpヘッダとして使う)
  • プロトコルセマンティクス
    • GETメソッドによるナビゲーション
  • アプリケーションセマンティクス
    • ない！
  • RFC5988で定義
  • 4章参照
  • 画像やpure JSONにハイパーメディアコントロールを付与する
  • relパラメータに任意のリンクリレーションを与える
  • Link Headerを使うと、pure JSONにprofileを結びつけることができる

Lication, Content-Location Header

  • media-type
    • なし(httpヘッダとして使う)
  • プロトコルセマンティクス
    • httpレスポンスコードに依存
  • アプリケーションセマンティクス
    • ない！
  • 1〜3章、付録B参照
  • RFC2616
  • Content-Location
    • 現在のリソースの正規の位置を示す
      • IANAで定義されたcanonicalリレーションと同等
  • Location
    • 201(Created)
      • 作成されたリソースへのリンクを示す
    • 301(Moved Prrmanently)
      • リダイレクト先を示す

URL List

  • media-type
    • text/url-list
  • プロトコルセマンティクス
    • ない！
  • アプリケーションセマンティクス
    • ない！
  • RFC2483で定義
  • urlの一覧を取得
  • リンクリレーションをもたないため、ハイパーメディアコントロールになり得ない

JSON Home Document

  • media-type
    • application/json-home
  • プロトコルセマンティクス
    • あって無いようなもの
  • アプリケーションセマンティクス
    • ない！
  • より洗練されたurl list
  • JSONオブジェクトのキーとしてリンクリレーション、値にUrlを指定
    • ハイパーメディアコントロールたり得る
  • URL Templateが使用可能
    • テンプレートスロットはhref-varsで指定されるprofileを参照する
  • hints を与えることで、メソッドを明示できる
    • "hints": { "allow": [ "POST" ] }
    • リンクのアプリケーションセマンティクスは指定できない
  • profileと組み合わせることで、human-readableなAPIをmachine-readableなものに変貌させることができる

Link-Template Header

  • media-type
    • なし(httpヘッダとして使う)
  • プロトコルセマンティクス
    • GETメソッドによるナビゲーション
  • アプリケーションセマンティクス
    • ない！
  • RFC6570で定義(時間切れで棄却)
  • 機能的にはLink Headerと同様
  • リンク先としてURL Templateが使用可能
  • var-baseパラメータを使って、スロット変数のためのprofileを指定する

WADL

  • media-type
    • application/vnd.sun.wadl+xml
  • プロトコルセマンティクス
    • 完全な汎用フォーマット
    • あらゆるweb APIのプロトコルを模倣できる
  • アプリケーションセマンティクス
    • 拡張のための最小限だけ
  • requestタグで任意のhttpメソッドを指定する
  • entity-bodyを含む、あらゆるhttpヘッダを指定できる
  • メタデータはXML Schemaを用いる
  • docタグにprofileを埋め込むことができる
  • いくつかのHAX-RSの実装がAPIとして、WADLを吐き出す
    • SOAP同様、インピーダンスミスマッチを生む要因となる

XLink

  • media-type
    • なし(任意のxmlに埋め込む形で使用)
  • プロトコルセマンティクス
    • GETメソッドによるナビゲーション
    • GETメソッドによるトランスクルージョン
      • リソースの埋め込みのようなもの
  • アプリケーションセマンティクス
    • ない！
  • 素のxmlにハイパーメディアリンクを埋め込む拡張
  • XLink自身、タグは定義されていない
  • xmlに付与する属性のみ定義
    • xlink:arcrole
      • URIを使ってリンクリレーションを表現する
    • xlink:show
      • ナビゲーション方法を変更する
        • replace
          • htmlのaタグのように内容を置換する
        • embed
          • htmlのimgタグのように内容を埋め込む

XForms

  • media-type
    • なし(任意のxmlに埋め込む形で使用)
  • プロトコルセマンティクス
    • GET(安全)、POST/PUT/DELETE(安全でない)メソッドによる、任意の状態遷移
  • アプリケーションセマンティクス
    • ない！
  • 素のxmlにハイパーメディアフォームを埋め込む拡張
  • XLinkとは異なり、自信のタグを定義している
    • xforms:model
      • htmlにおけるformタグと同機能
    • xforms:submission
      • xforms:modelの子要素
      • htmlにおけるformタグのaction属性とmethod属性を担う
    • xforms:instance
      • xforms:submissionの子要素
      • GETメソッドのクエリ文字列やPOSTメソッドのentity-bodyの構築方法を例示する
    • xforms:input
      • htmlにおけるinputタグと同機能
    • xforms:submit
      • htmlにおけるinput type="submit"と同機能

後編へつづく

RESTful Web APIs 読書メモ(11)

rest