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, Oct 03 '15 at 08:19
Make sense. So I just don't understand why GitHub, Heroku and Twitter use the first method. — Tony Han, Oct 03 '15 at 12:19

Paul Sweatte · Answer 1 · 2017-06-03T18:38:41.647

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 Answers1