「Web API: The Good Parts」読書メモ 3章~4章

◼︎ 概要

「Web API: The Good Parts」3章読書メモ 気になったところをメモ程度にまとめます

• 「Web API: The Good Parts」読書メモ 1章~2章
• 「Web API: The Good Parts」読書メモ 3章~4章
• 「Web API: The Good Parts」読書メモ 5章~6章

◼︎ 本について

水野貴明著「Web API: The Good Parts」（オライリー・ジャパン発行）

Amazon or オライリー・ジャパン公式サイトにて販売中

◼︎ 3章

目次

3. レスポンスデータの設計
   1. データフォーマット
   2. JSONPの取り扱い
   3. データの内部構造の考え方
   4. 各データのフォーマット
   5. レスポンスデータの設計
   6. エラーの表現

気になったところ

• レスポンスのデータフォーマット
  • JSON一択
  • 要望があって余裕があればXMLもあるといい
• データフォーマットの指定方法

  • 方法	使用例
    クエリパラメータを使う	https://api.example.com/v/users?format=xml
    拡張子を使う	https://api.example.com/v/users.json
    リクエストヘッダでメディアタイプを指定する	GET /v1/users Host: api.example.com Accept: application/json

• JSONP
  • [Web] JSONPを用いてクロスドメイン制約を超える が参考になる
• Chatty  API
  • Chatty(おしゃべりな) API: 1つの作業を完結させるために複数回APIアクセスが必要になるAPIの設計
  • Chatty APIは良くない
• エンベロープ
  • 全てのデータ(レスポンスやリクエスト)を同じ構造でくるむこと
  • HTTPがエンベロープの役割をするのでやるべきでない
• 配列
  • レスポンスを配列で返すとJSONインジェクションされる可能性がある
  • 従って配列をオブジェクトで包むなどの工夫が必要
• レスポンスデータの名前
  • キャメルケースが良い
    • JavaScriptの命名規則においてキャメルケースの利用がルール付けされているケースが多い
    • GoogleのJSON style guideでもキャメルケースを利用することが明記されている
  • 少ない単語数
  • 変に省略しない
  • 他のAPIを参考にする
  • 単数形/複数形に気をつける
• 日付のフォーマット
  • RFC 3339を使うのが良い(例：2016-02-03T04:05:06+09:00)
• 整数の限界
  • int型は表現可能な数が決まっているため巨大な数をJSONで返す際は文字列として返すと良い
  • Twitterではidの他にid_strという数値を文字列として格納したものを返す

◼︎ 4章

目次

4. HTTPの仕様を最大限利用する
   1. HTTPの仕様を利用する意義
   2. ステータスコードを正しく使う
   3. キャッシュとHTTPの仕様
   4. メディアタイプの指定
   5. 同一生成元ポリシーとクロスオリジンリソース共有
   6. 独自のHTTPヘッダを定義する

気になったところ

• メディアタイプ
  • 簡単に言うとデータ形式のこと
  • レスポンスではContent-Typeというヘッダを利用して指定する

  • 例	どういったものか
    Content-Type: application/json	レスポンスデータがJSONであることを意味する
    Content-Type: image/png	PNG画像であることを意味する

  • 記述方法
  • トップレベルタイプ名 / サブタイプ名 [ ; パラメータ ]

  • 名前	意味
    トップレベルタイプ名	そのデータ形式が大別してテキストなのか、画像なのかなどカテゴリを表す
    サブタイプ名	具体的なデータ形式
    パラメータ	付加情報を付ける場合に利用する

  • リクエストではContent-TypeとAcceptを使う
  • Accept: どんなメディアタイプを受け入れ可能かをサーバに伝える
• クロスオリジンリソース共有
  • 参考：CORS(Cross-Origin Resource Sharing)について整理してみた

◼︎ 終わりに

3章4章ではステータスコードについての話とキャッシュの話などが出てきたのですがこのページでまとめるとボリュームが増えてしまうので省略しました
ためになりそうな話だったのでいつか別途まとめるかもしれません

続き：「Web API: The Good Parts」読書メモ 5章~6章