レスポンスデータの設計について

自分向けメモです。
WebAPI The Good Partsという本をよく理解するためのメモです。

データの内部構造の考え方

なるべく少ないAPIアクセスのほうが良い。
APIがバックエンドのテーブル構成を愚直に反映させる必要はない。

返してくれるJSONはオブジェクトで包んだほうがいいよ。
JSONインジェクションを防ぐために。

返すJSONは、なるべく階層構造を持たないほうがいいけど、階層構造を持ったほうがわかりやすいのなら、持ったほうが良い。

配列に続きが存在する場合、すべての要素を見るのではなく、必要な件数+1件を見て、次の要素が存在するかどうか考えれば良い。

各データの名前は、JSに準じてキャメルケースにするのが良さそう。
一覧取得するエンドポイントの場合、名詞を複数形にした方がいいよね

よっぽどのこと(データ転送量的な問題)がない限り、各データの名前に変な文字の省略形は使わないほうが良い。

日付のフォーマットに関して、日本人にはRFC3339というフォーマットが馴染みやすそう。
HTTPヘッダに日付を入れる場合は、RFC822/RFC850/ANSI C のみが対応だから注意。

IDが非常に大きくなるとき、64bit整数型を使うより文字列を扱ったほうが桁あふれによる誤差が生じずに済む。

クライアント側で利用したいデータとAPIが返すデータ構造が同じだと楽だよね。
ここで、データベースのテーブルと同じデータ構造を返す必要はない。

HTTPのステータスコードを最大限利用して、エラーを返すの大事。
しかし、HTTPのレスポンスヘッダorレスポンスボディにエラーの詳細を入れることで、具体的なエラーの原因がわかるようになる。

エラーの際、フレームワークのエラーの場合のデフォルトHTMLが表示されることを防ぐ。
どんなエラーの場合でも、適切なフォーマットでデータが帰ってくるの大事。

メンテナンスのときは、ステータスコード503で意図的にサービスを停止していることを伝える。
メンテナンスの終了予定時刻もだいたい決まっているのなら予めエラーメッセージとして伝える。
メンテナンス時間を余裕を持って伝えたほうが良い。
予定より短く済んで怒る人はいないから。