Which format is better for list in JSON API design, flat array or nested object?

Question

For list API, such as Users, I find that there are two common formats. Arrays:

// flat array
[
  {
    "login": "octocat",
    "id": 1
    ...
  },
  ...
]

GitHub, Heroku and Twitter use this format

VS Objects:

{
  "results": [
    {
      "login": "octocat",
      "id": 1
      ...
    },
    ...
  ]
}

Parse and Slack and instagram use this format.

Which one is better? How to compare these two formats?

I would argue that the second method is more extensible. It is backwards compatible in the event that you'd like to, for example, include some metadata in the object under another member name. The first method would be guaranteed require a breaking change in the event that you wanted to add to the schema. — CollinD
– CollinD, Commented Oct 3, 2015 at 8:19
Make sense. So I just don't understand why GitHub, Heroku and Twitter use the first method. — Tony Han
– Tony Han, Commented Oct 3, 2015 at 12:19

Paul Sweatte · Accepted Answer · 2017-06-03 18:38:41Z

Array-oriented data has the following advantages:

and disadvantages:

Key/Value-oriented data has the following advantages:

JSON.parse works in client-side JavaScript
Namespacing makes duplicate values easier to disambiguate
JSON.stringify works to make simple transformations easier compared to array methods

and disadvantages:

It can be hard to iterate nested hierarchies without a library in client-side code
JSON.parse in client-side code removes duplicate key names on the same level

References

1 Answer 1