【API】返すJSONデータの中身について

エンベロープは必要か？

エンベロープ（日本語でいえば封筒）とは以下のような形式のデータ以外の付加情報のことです。一見すると統一的なフォーマットに見えますが、結論から申しますと冗長なので必要ないです。

なぜエンベローブは不要か？

Web APIは基本的にHTTPを利用していてHTTPがエンベローブの役割を果たしているためです。HTTPにはヘッダがあってそのヘッダがエンベローブの役割を果たしています。より詳細な情報はHTTPヘッダに入れるようにすれば良いです。

レスポンスステータスや、レスポンスヘッダなどはHTTPレスポンスヘッダに全て入れ込んで仕舞えば良いでしょう。

ただ、一部例外があってJSONPをクライアントライブラリとして利用している場合はブラウザでデータを読み込む場合はステータスコードやレスポンスヘッダにアクセスすることができないのでその場合はエンベローブはあった方が良いでしょう。

データはフラットにすべきか？

階層化するとJSONのデータ容量が増えるのでできるだけフラットにするのが望ましいでしょう。必要があった場合は階層化するという方式が良いです。

配列とオブジェクトの使い分け

JSONはトップレベルに配列もオブジェクトもどちらでも配置することが可能ですが、どちらかといえば以下の理由でオブジェクトをトップレベルにした方が良いです。

• レスポンスデータが何を示しているのかわかりやすくなる。
• セキュリティ上のリスクが低くなる。（JSONインジェクション攻撃に強くなる。）

配列

• 順序が保証される。
• データはわかりづらい。

オブジェクト

• データ構造がわかりやすくなる。
• 順序が保証されない。

日付の表現方法

いろいろな日付形式がありますが、RFC 3339を使うのが良いでしょう。インターネット上で用いる標準形式として定められたフォーマットです。

形式名	例	特徴
RFC 822(RFC1123で廃止)	Sun,12 Dec 2004 08:12:10 GMT
RFC 850(RFC1036で廃止)	Sunday,12 Dec 2004 08:12:10 GMT
ANSI Cのasctime形式	Sun Dec 12:11:34:21 2004
RFC 3339	2004-11-1211:34:22+09:00
Unixタイムスタンプ(epoch秒）	128473838	1970年1月1日からの経過時間を秒で表す。