Web API: The Good Parts 読んだ

某氏にいわれて下書きまで書いてたのを思い出したので、要約ほどではないけど感想文として提出。

個人的には第3章が良かったです。

Web API: The Good Parts

はじめに

これを読んで一番トクするのは、もちろんサーバーサイドで実際にAPIを実装する人かなとは思います。

とはいえ、
クライアントサイドからどういうデータ形式が欲しいかって話ができないと、
今の時代のクライアントのコードは書けませんよね？

そういう意味では、xhrでデータの取得をしたことがあるって人みんなにとって、
一見の価値ありなのではとも思います。

第3章: レスポンスデータの設計

この章は実際にエンドポイントを叩いたときのレスポンスについての章です。
ここがオススメな章なので、特にここだけ書き残しておきます。

汎用的と思って不要なデータをつけるのはやめよう

レスポンスを以下みたいなデータ形式で統一して返す必要は、本当にあるか？って話。

// okなとき
{
  header: {
    status: 'ok',
    code: 0
  },
  body: {
    // ...
  }
}

// ngなとき
{
  header: {
    status: 'ng',
    code: 1
  },
  body: {
    // ...
  }
}

そういうのはHTTPヘッダにさせれば良い。
ステータスコードは200やけど、でもAPI的にはエラーみたいなのはありがちやけどやめましょうっていう。

データ構造はまずはフラットに作って、必要であれば構造化

まあデータ量にもよると思うけど・・。

とはいえ、方針としてなるべくフラットに作っておけば、
データが増えてきたとしてもクッション構造の部分の量は少なくとも制限できてるので、
最初からきっちり構造化する必要はないですよという指針。

配列ではなくオブジェクトを返そう

// こんなデータより
[1001, 1002, 1003]

// こっちのがわかりやすいよね
{
  user_ids: [1001, 1002, 1003]
}

• レスポンスのデータだけを見たときに、何のデータかわかりやすい
• 配列に統一はできないがオブジェクトに統一はできる
• JSONハイジャック対策にもなるよ

Backboneとかさわってると、Modelにデータつっこむ都合でオブジェクトの方が嬉しいとかありますよね。

プロパティ名の考え方

• そもそも命名規則に関してや
• 多様化しがちな日付のフォーマット
• 4294967295を超えるIDどうするよとか

知っ得知識がそこにはありました。

エラーについて

エラー時に返すデータの構造について。

• 適切なステータスコードを返す
• エラーに限っては構造を統一してわかりやすく示すべき
• エラーページのHTMLとか返さないように注意
• ログインエラーでID or PWどっちか間違ってるみたいにぼかすのはセキュリティのため

おわりに

APIを設計・実装しないにしても、
単純にサーバーサイドテンプレートに値を渡す部分でも使える知識。

クライアント側の普段のコードでも、何かのメソッドでオブジェクトを返すシーンはあるはずで、
そういう場所でも参考にできる部分は多々あるなーと。

URLの設計からHTTPの仕様からセキュリティの話から割と体系的にまとまってて、
読んでよかったなーと思います。

もひとつおわりに

サーバーサイドエンジニアではない身からすると良かったんですけど、
ただ実際に設計・実装したことがあるサーバーサイドのエンジニアさんが見ると、いまさら感満載なんやろうなーとは思います。(Amazonのレビューとか)

まあ経験に勝る知識はないよって話か。