【REST API】レスポンス JSON の array 型は要素がないときに何を返却するべきか
はじめに
REST API の設計をしていて、レスポンスの array 型のフィールドは要素がないときに何を返却するべきか迷ったので、整理する。
候補
フィールドの仕様の候補としては、下記を考えている。
僕は下記の理由で #2 を推す。
- フィールドの存在チェックや null かどうかのチェックが不要で、扱いが楽だと思う。
- 要素が無い配列（空配列）も、配列としては不正ではないので、array 型のフィールドは空配列を返すのが正しいと思う。
| No. | フィールドの仕様 | 返却するもの |
|---|---|---|
| 1 | 任意フィールド | フィールド自体を返却しない。 |
| 2 | 必須フィールド | 空配列を返却する。 |
| 3 | 必須かつ Nullable フィールド | null を返却する。 |
JSON の仕様
JSON の仕様は RFC 8259 で定義されている。
- 配列構造は、0個以上の値（または要素）を囲む角括弧として表される。要素はカンマで区切られる。
- 配列の値が同じ型である必要はない。
- Arrays
An array structure is represented as square brackets surrounding zero or more values (or elements). Elements are separated by commas.
array = begin-array [ value *( value-separator value ) ] end-array
There is no requirement that the values in an array be of the same type.
JSON の仕様としては、空配列を返却するのが正しそう。
Google JSON Style Guide
Google が定めている JSON のスタイルガイドでは下記のルールとなっている。
- フィールドが optional もしくは値が null または空の場合は、特別の理由がない限りフィールド自体を削除する。
Empty/Null_Property_Values - Google JSON Style Guide
Consider removing empty or null values.
If a property is optional or has an empty or null value, consider dropping the property from the JSON, unless there's a strong semantic reason for its existence.
結論
Google JSON Style Guide を参考にして、下記のルールとする。
- null を API のインターフェイスに持ち込まない。
- 値が null または空の場合は、フィールド自体を返却しない。
- 従って、値が null または空になりうるフィールドは optional にする。
- 取得するかどうかを利用者が選択できるフィールドは optional にする。
※ array 型のフィールドが空配列を返却することはない。
なぜ、このルールか
- 値が空の状態は array 型以外にも存在する。そして、空の状態を表現できない型も存在する。
- よって、空の状態を
""や[]で表現するのは、一部の型限定のルールになってしまう。 - 「array 型は常に必須フィールドにして、空の状態を
[]で表現する」というルールにすることも可能だが、インターフェイスの定義上「要素が0件の状態もありえるのか」が分からないという問題があると思う。 - シンプルでかつAPIの利用者が仕様を理解しやすいルールとしたいので、空の状態を null やフィールド自体を返却しない方法以外で表現するのは辞める。
- また、レスポンスのインターフェイスの各フィールドの状態を 値が返却される or フィールド自体が返却されない のどちらかに限定するために、null を API のインターフェイスに持ち込まない。
空の状態の表現方法
| 型 | 空の状態の表現方法 |
|---|---|
| number | 表現不可 |
| string | "" |
| boolean | 表現不可 |
| array | [] |
| object | {} |
array 型のフィールドの仕様
| 要素の仕様 | フィールドの仕様 |
|---|---|
| 0件のときもありえる | optional（0件のときはフィールド自体を返却しない） |
| 常に1件以上 | required |
おわりに
自分の中での一定のルールができた。
けど、モヤモヤは残っている。業務の中でを引き続き API 設計のスキルを磨いていく。
モヤモヤ🤔
array 型である以上、利用者側は [] が返却されることを想定した作りにするのでは。
つまり、利用者側は array 型のフィールドについては [] が返却されることを想定した作りにするから、下記は問題にならないのでは（「要素が0件の状態もありえるのか」が分かる/分からないに関係なく [] が返却されることを想定したつくりにするから関係ないのでは）。
「array 型は常に必須フィールドにして、空の状態を
[]で表現する」というルールにすることも可能だが、インターフェイスの定義上「要素が0件の状態もありえるのか」が分からないという問題があると思う。
optional の場合、利用者側は「フィールド自体が返却されない」ことも想定しないといけない。array 型は常に required にするのが、利用者側的には楽なのでは。
| 要素の仕様 | 利用者側が想定すること |
|---|---|
| optional の場合 | ・フィールド自体が返却されない。 ・ [] が返却される。・1件以上の要素が返却される。 |
| required の場合 | ・[] が返却される。・1件以上の要素が返却される。 |