REST API JSONペイロードの配列で常に単一のオブジェクトを返しますか？

私が取り組んでいるREST APIの場合、一貫したレイアウトでJSONを返したいです。

{
  "Data" : {
     "Id" : 123,
     "Email" : "charlie@somewhere.com"
     "Firstname" : "Charlie",
     "Surname" : "Brown",
 },
 "Error" : null
}

ペイロードには常に「データ」と「エラー」が含まれ、どちらかがnullになる可能性があります。

私の質問は、「データ」と、実際には1つのオブジェクトしか返さないエンドポイントに関するものです。たとえばusers/current、現在認証されているユーザーを返すAPI があるとします。上記のようにそのユーザーを返したでしょう。「Data」という名前の単一のJSONオブジェクト。

ゼロ、1つ以上のオブジェクトを返す可能性のあるエンドポイントの場合、（もちろん） "Data"を配列にします。

{
  "Data" : [
    {
      (first object)
    },
    {
      (second object)
    }
  ],
  "Error" : null
}

一貫性を保つために、「データ」は常に配列でなければならないという見方を聞いたことがあります。エンドポイントが論理的に1つのオブジェクト（またはnull）のみを返す場合でも。

他の人はどう思いますか？複数のオブジェクトが返されない場合は、「データ」と配列を作成する必要はないと思います。

この種の一貫性は見当違いです。

配列にデータをラップしても、APIの利用者にはメリットがありません。実際のデータの解釈方法を知っている必要があるためです。例として、それはの「データ」の結果ということだけではない可能性がある/users/currentとは、/cities/chicago/restaurants同じコードで処理しようとしています。

一方、エラーの場合は、すべてのエラーが同じエラー処理コードによって処理される可能性が高く、同じ構造を使用する利点があります。

これを自問してみてください：これがお気に入りのOOP言語のクラスである場合、一貫性のためにすべてのメソッドが同じ型を返すようにしますか？

受信側でJSONメッセージの一般的な受信者が必要な場合は、データノードを同じ形式にすると便利です。したがって、この場合は常に配列があると便利です。そのため、毎回同じ方法で解析できます。

各応答は、個別に（異なる方法とは異なるAPI呼び出し）に処理されようとしている場合は、私は、あなたのポイントを見ることができるが、それは、配列または1つのオブジェクトが返されるとき（APIコールからの）絶対的に明確にする必要があります。

真の一貫性を提供していないため、私は配列のアプローチのファンではありませんこれらのシングルトンアレイでは、できるだけ早くアレイを作成してください。それでも、2つの異なることを行う必要があります。

ただし、配列を使用する場合は、Dataがnullにならないようにしてください。データがない場合、配列は空になります。それは私が見ることができる唯一の利点です。

私はいつも配列を返す側に落ちています。クライアント側では、すべてのユーザーを取得するか1つだけ取得するかに関係なく、「Users」応答オブジェクトを使用します。配列を返すエンドポイントと、同じオブジェクトを返すが複数ではないエンドポイントがある場合でも、配列を使用します。

サーバー側で同じロジックを使用する場合も同様の引数があります。クエリが1つのアイテムを返す場合でも、複数のアイテムを返す場合でも、同じコードを使用してください。

唯一の例外は、どのようなコンテキストでも、配列として存在することのないオブジェクトを返す場合です。その場合、必要はありません。