APIのレスポンスは可変項目を避ける

1. 原則

APIのレスポンスは可変項目を避ける

• APIのレスポンスは可変項目を可能な限り避けるべきである
• 可変項目とはデータによって存在したりしなかったりする項目のことである
• 例えば、↓のようなデータ項目を指す（familyの有無で項目自体があったりなかったりする）

# familyを持つデータ
{
    "user": {
        "name": "USER1",
        ...
    },
    "family": [
        ...
    ]
}

# familyを持たないデータ
{
    "user": {
        "name": "USER2",
        ...
    }
}

• データが存在しないことを示すには可変項目ではなく、該当の項目をNullもしくは空配列にするべきである
• 特にトップレベルの項目は可変項目とすることは避けるべきである

# familyを持たないデータ
{
    "user": {
        "name": "USER2",
        ...
    },
    "family": []  # familyを持たないので空配列
}

2. 根拠

クライアントに無駄な実装を強要することになる

• クライアントの実装時、可変項目の場合はレスポンスに対象の項目が存在するか↓のように毎回チェック処理を入れる必要がある

data = get_api_data()

if 'family' in data:
    for item in data['family']
        # 何かの処理
        ...

• 項目の内容がNullあるいは空配列ならチェック処理自体が不要になる

data = get_api_data()

for item in data['family']
    # 項目の中身がNull or 空なら実行されず抜けていく処理
    ...

• 結果的に同じことをやっているわけだが、同じことをするならより手数が少ない方が理解しやすく不具合も起きづらい
• という事は、可変項目はクライアント実装者に無駄な実装を強要することになる為、好ましくない

フォーマットチェックが複雑になる

• APIのレスポンスのフォーマットチェックを行いたい場面はそれなりに存在する
• そのような時、可変項目はオプショナル項目という形でチェックする必要があるが、そのチェックは実装もテストも複雑になりやすい
• 多少の努力や工夫で解決可能な問題ではあるが、そのような努力をしてまで可変項目を使うメリットがあるかは疑問である

ドキュメントの記述内容が複雑になる

• APIインターフェイス仕様書にはレスポンスの仕様とサンプルが記述されるべきである
• 可変項目は事実上複数のレスポンスデータを返すことと同じである為、レスポンスデータのサンプルも複数バージョン記述する必要が出てくる
• 当然、ドキュメントの作成/更新コストも上昇する

3. 指針

レスポンスデータは可変項目を避け、Nullか空配列を返すよう設計する

• データが存在しないことを示すにはNullか空配列を返すよう設計する
• 特にトップレベルの項目に対する可変項目は避けるべきである
• NULLと空配列の選択基準は、オブジェクトが存在しない場合はNULLを設定し、リストの中身が存在しないことを表す場合は空配列を設定する

4. 注意

• 特に無し

参考資料

• 特に無し