Expect top-level JSON objects instead of arrays

[alex-knowles]

Edit: I changed the example object name to "data" instead of "poems".

Requesting a poem index might return something like:

[
    {
        "id": 3,
        "title": "Foo",
        "author": "Baz",
        "collection": "Where the Sidewalk Starts",
        "text": "This is\nNOT\na         poem."
    },
    {
        "id": 4,
        "title": "Bar",
        "author": "Quux",
        "collection": "Where the Sidewalk Starts",
        "text": "This is\nNOT\na         poem."
    }
]

However, there is some conventional wisdom against returning top-level JSON arrays. Instead, clients should expect the server to return the array wrapped in an object. For example:

{
    "data":
    [
        {
            "id": 3,
            "title": "Foo",
            "author": "Baz",
            "collection": "Where the Sidewalk Starts",
            "text": "This is\nNOT\na         poem."
        },
        {
            "id": 4,
            "title": "Bar",
            "author": "Quux",
            "collection": "Where the Sidewalk Starts",
            "text": "This is\nNOT\na         poem."
        }
    ]
}

[michelmansour]

I support this.

[alex-knowles]

Note: I made a minor change to the example JSON posted above.

Previously, the top-level JSON object was named "poems". I changed it to "data". This is the default name generated by Phoenix. It is trivial to change, but "data" is a good default because it is predictable and generic for client consumption.