RESTful Web APIs 読書メモ(8)

Chapter 8. Profiles

アプリケーション特化の拡張機能に対するドキュメント化
アプリケーション特化の用語の定義、ドキュメント化
現在、一般的用いられていることは、大量のhuman-readableなドキュメントを作成すること
- APIドキュメントについてはRESTful(自己記述性メッセージ)でない

media-typeを元にリソースを解析しても得られない仕様(APIドキュメント)
- たいていHuman-readableな文書
- machine-readable profile
  - linkやdescripterで記述されたhuman-readableなドキュメント(Profile)を自動収集できる
定義(RFC6906)
- リレーションを使用してProfileとリンク(rel="profile")
  - IANAにそのリレーションが登録されている
    - relをサポートするあらゆるハイパーメディアコントロールで利用可能
      - htmlのaタグ
      - html, Collection+JSON, HALのlinkタグ
      - RFC5988のLINKヘッダ
  - Ontent-Typeパラメータに追記
    - application/collection+json;profile="(リンク先URL)"
    - すべてのmedia-typeで使用できるわけではない(RFC4288)
      - Collection+JSON
      - JSON-LD
      - HAL
      - XHTML
    - httpヘッダでprofileリンクを示したいなら、すべてで使えるLINKヘッダを使うべき
  - Microdataのitemtype
    - Urlで、リンク先のprofileを指定する

どのようなHTTPリクエスト発行されるのかについて
フリーフォームな文体で記述
ハイパーメディアコントロールを持たないmedia-type(JSON)に対して用意
HALのようにプロトコルセマンティクスが削ぎ落とされている場合に用意
ハイパーメディアコントロールであれば、リンクリレーションを用いて指定
- ハイパーメディアコントロールから駆動される状態遷移を記述した文字列
  - GETでアプリケーション状態を遷移
  - POST, PUT,DELETEでリソース状態を遷移

元のJSONドキュメントに"context"と呼ばれるmachin-readableドキュメントを組み込む
APIの変更なしに組み込むことが可能
RDFからの派生
アプリケーションセマンティクスを直接説明せず、ハイパーメディアリンクを添えるだけ
- "n":
- "photo_link": { "@id": , "@type": "@id" }

APIにhuman-readableドキュメントを埋め込めるフォーマットを用いる
- HTML
  - inputタグのvalue属性
- HAL
  - linkタグのtitle属性
- Siren
  - actionオブジェクトのtitleフィールド
machine-readableとhuman-readableドキュメントの両方を用意することについて
- 人との対話により動くクライアント、自動化クライアントの両対応のため
- 両方のセマンティクスギャップをより縮める