RESTful Web APIs 読書メモ(2)

Chapter 2. A Simple API

GETリクエスト

  • リソース状態の変更は意図しない
    • アクセスカウンタやログ保存のような付随した事象の変更はOK

  • 安全なメソッド

  • 過去にGETリクエストで、リソース状態の変更がしばしば行われていたが、これは間違った設計

レスポンス

  • status code
    • リクエストがどう処理されたかという結果をクライアントに知らせる
  • entity-body
    • ドキュメント本体
  • レスポンスヘッダ
    • entity-bodyを記述するためのKey-Valueペア
    • status codeの後、entity-bodyの前に送られる
    • content-type
      • どんなentity-bodyが返されたかクライアントに知らせる
      • media-type

JSON

  • APIレスポンスの表現として用いられるフォーマット(RFC4627)

Collection+JSON

  • Publishing APIの目的で用いることができるフォーマット
  • 6章参照
  • 利用可能なリソースの一覧を発行するための標準
  • collection, items, valueのそれぞれにhrefプロパティをもつ
  • リスト、明細、フォームテンプレート、検索結果のいづれでも同じフォーマット

  • hrefと名付けられたとき、その内容はかならずURI

  • Collection+JSONを使った、itemの追加

    • template構造に基づいて、内容を埋める
      • content-type: application/vnd. collection+jsonでPOSTリクエストを発行する
      • 成功したら、ステータスコード201を返す
      • また、レスポンスには新しいリソースのURIを含めておく
      • 新しく作成されたリソースもまたGETリクエストで取得すると、それもまた、Collection+JSON

POSTリクエスト

（なんかまとめづらい内容なので省略）

アプリケーションセマンティクスがセマンティクスギャップを作ること

  • アプリケーションセマンティクス

    • アプリケーション特有の構造
    • media-typeのフォーマットとしては規定されていない構造

  • 標準化された、もしくは互いに合意されたアプリケーションセマンティクスであれば、セマンティクスギャップ消失する

  • あえてセマンティクスギャップを広げることで、APIに差別化をもたらすことができるかもしれない

つづき・・・

RESTful Web APIs 読書メモ(3)

rest