web-dev-qa-db-ja.com

REST API?からのJSON応答にnull値を含める必要がありますか?

現在、RESTful APIの設計と開発を進めています。私はAPIに対して実用的でリソース指向のアプローチを取っています(リソース指向、統一されたインターフェース、アドレス指定可能性、しかし実際のHATEOASはありません)。ただし、オブジェクトのnull値にどのようにアプローチするかについてはよくわかりません。

API応答にnull値のフィールドを含める必要がありますか?

例:

{
    "fieldA": "AAA",
    "fieldB": null
}

または、システムにこれらのフィールドのデータがない場合、これらのフィールドを完全に除外する必要がありますか?

例:

{
    "fieldA": "AAA"
}
42
Dennis Laumen

これについては最近 API-Craft で議論がありました。一般的なコンセンサスでは、値のomissionとnull値の包含との間に意味的な違いがある可能性がありました。

特定のユースケースで得られるセマンティック値がない場合は、APIのターゲットコンシューマを見て、値を省略すると問題が発生するかどうかを検討します。

22
Pete

明確な勝者はありません。そして、クライアントは存在しないので、クライアントはこれに関する規約に技術的に依存するべきではなく、クライアントはどちらの形も期待すべきではありません。

  • 帯域幅の使用を減らすためにnull値を削除するは、一般的には正当化されません(nullフィールドの数が多く、帯域幅が著しく低下しない限り)。
  • 人間の読者が実際の値をより簡単に確認できるようにnull値を削除は一般的に正当化されず、APIはマンマシンインターフェイスではありません
  • 人間の読者がドキュメント構造をより簡単に見られるようにnull値を保持するは一般的に正当化されず、APIはマンマシンインターフェイスではなく、API応答はAPIドキュメントではありません
  • ダーティなクライアントが特定の方法でjsonを解析できるようにnull値を保持は一般的に正当化されず、クライアントは寛容なリーダーとしてきれいに書かれるべきです
  • 対応するcreateメソッド(POST/PUT)が明示的にnullを渡す必要がある場合のみnull値を保持するは理にかなっていますが、一般的に達成するのは困難です
  • 作成中の出力を要求と同じに保つ各ドキュメントが独自のクライアントを持っている場合は意味がありますが、一般的に達成するのは困難です
  • 考慮する特別なケースは、?fields=foo,bar他のすべてのフィールドにnullを返すのは少し直感に反するように見える
8
tkruse