RESTful Web APIs 読書メモ(6)

Chapter 6. The Collection Pattern

  • コレクションもまたリソース
    • コレクションに含まれるリソースは"item"や"entry"、"member"と呼ばれる
  • Pagenation
    • 大量のコレクションメンバーを持つ場合、全てを一度に返すことは通常しない
    • 最初の一部だけをコレクションとして返し、残りはrel="next"を付与したリンクだけを提供する
      • nextはIANAで登録されている
      • ほかにprev, first, lastもIANAで定義されている
    • Collection+JSONはリレーションを明示的にサポートしてはいない
      • 必要ならリレーションを組み込めばいい

Collection+JSON

  • 問題領域とは独立した汎用フォーマット
  • 手軽にREST制約を組み込める
  • httpを介して取得するリソースのためのプロトコルセマンティクス
  • プロパティ
    • href
      • コレクション自身へのリンク
    • items
      • コレクションの要素
      • アプリケーション特化データの集合
        • href
          • 要素へのリンク
          • GETリクエストで単独のリソースとして取得できる
          • PUTやDELETEで変更、削除
        • links
          • 要素に関連するほかのリソースへのリンク
          • 例えば、本リソースに対する著者、出版社等
          • render="link"
          • render="image"
        • data
          • 要素を構成する内容
          • アプリケーションセマンティクスの要
          • "name"と"value"から成るJSONオブジェクトの集合
          • 各ペアには備考として"prompt"をもたせられる
    • links
      • コレクションに関連するほかの要素
    • queries
      • コレクションを検索するためのテンプレート
    • templates
      • コレクションに新しい要素を加えるためのテンプレート
    • error
      • エラーメッセージ

AtomPub

  • Atomフォーマット
    • RSSに代わり、ニュースを同報する仕組みとしてRFC4287で標準化
    • ニュース記事を一つ以上のカテゴリに分類できる
  • AtomPubはニュースを編集 / 発行(CRUD)などを行うためのAtomフォーマットを使ったワークフロー(RFC5023)
  • media-typeはapplication/atom+xml
  • 新しいエントリーはURIにPOSTすることで行う
  • リンクにrel="edit"を付与することで編集可能なエントリーであることを示す(PUTサポート)
  • Collection+JSONと同じコンセプトをもつ
    • コレクション要素は"item" -> "feed"
    • Collection+JSONは汎用フォーマットなので、itemに特別なアプリケーションセマンティクスわ定義していない
    • AtomPubはニュース配信プロトコルなので、エントリーはニュース記事
  • コレクションパターンのプラグイン基盤としても用いられる
    • Atom Threading Extension
      • RFC4685
      • メールスレッド表現
      • rel="replies"
    • Atom deleted entry element
      • RFC6721
      • エントリーを削除するのではなく墓石を置削除扱いとする
    • Feed Paging and Archiving
      • RFC5005
      • アーカイブフィードコンセプトを定義
      • 複数のリソースをまたがるきょだなフィードをPagingする方法
      • rel属性として、next-archive, prev-archive, currentを使う
    • OpenSearch
      • xmlベースの検索プロトコル標準
      • rel="search"
      • Collection+JSONにおけるqueriesプロパティど同等のもの
    • PubSubHubbub
      • Atomフィードが更新されたときに通知を行うためのプロトコル
      • rel="hub"
    • これらのリレーションは全てIANAに登録されている
      • 何の説明もなく使用できる
  • プロパティ
    • feed
      • ID
        • 一意的にニュースを識別するためのもの
      • title
        • 見出し
      • subtitle
      • author
      • date, time
        • 発行日時 / 最終更新日時
  • アプリケーションセマンティクスのためにプロパティを拡張することが認められている
    • Googleでは、マップ上のシンボル、カレンダー、スプレッドシートのセル、ビデオ用に付加的な表現を拡張している(GData)

OData

  • AtomPubベース
  • MSが協力しているのでVisual studioから使いやすい

Hydra

  • あまり表舞台では見かけない

Semantics Challenge

  • ドメイン特化なフォーマットの場合(MAZE+xml)

    • カスタムタイプ、リンクリレーションがセマンティクスギャップを埋める
      • カスタム定義したハイパーメディアタイプ
      • 問題空間のために定義されたリンクリレーション

  • コレクションパターンは2種類のリソースタイプに大別される

    • item-type
      • GET, PUT, DELETE
      • 内容+ item自身へのリンクをもつ
    • collection-type
      • GET, POST(as append)
      • item-typeリソースをメンバーとしてもつ

  • collection-typeはリンクリレーションによるナビゲーションでアプリケーションセマンティクスを定義する

    • first, next, search

  • item-type

    • 一般的に定義されたアプリケーションセマンティクスはない
    • Collection+JSON
      • item-typeリソースの意味は、prompt要素にhuman-readableな説明として記述される

  • 同じドメインでも、APIが異なれば、アプリケーションセマンティクスは異なる

    • text or content
    • post ot blogPost
    • etc,…

つづき・・・

RESTful Web APIs 読書メモ(7)

rest