Why should I put JSON server responses under a `data` field for can.Model?

Question

On CanJS.com, it says not to return an array from a JSON service by itself. Instead, it should look like this:

{
    "data": [
        {"id":1, "description":"Do the dishes."},
        {"id":2, "description":"Mow the lawn."},
        {"id":3, "description":"Finish the laundry."}
    ]
}

Why is this necessary, and does it only apply to Arrays or does it apply to all Objects? For instance, should a single object response look like this?

{
  data: {"id": 5, "createdAt": 2234234329}
}

Or if there's only one data item, is the data field no longer necessary? For example:

{
 "id": 5, "createdAt": 2234234329
}

Answer 1

This is primarily a security issue for JSON data sources. Under "Talking to the Server" on CanJS.com, it says:

findAll will also accept an array from the service, but you probably should not be returning an array from a JSON service.

This links to a page about a JSON vulnerability which explains that since an array-only response is considered valid JavaScript when loaded with src from a script tag, this can be used to expose secure data with an XSS-like attack. By namespacing your array, you're mitigating an attack.

CanJS will handle a plain JSON array response, but there's a security problem with array-only JSON responses. If you're only loading an individual data item, a single object will be fine. However, if you need to load a list, you need to use an Array somewhere so can.Model.List can process it correctly--putting it under a data key allows it to do so without creating a security risk.

Additionally, when you namespace your data properly, you can include other properties that will be loaded along with can.Model.List as mentioned in asavoy's answer.

Answer 2

For endpoints that return a single model instance, it's fine to return this:

{
    "id": 1, name: "bob"
}

For endpoints that return a list of model instances (and this is what the docs are referring to), the array is recommended to be kept under a data key. That way it will work automatically, and you can add pagination data more easily. Fields other than data will be added to the can.Model.List object.

{
    "data": [
        { "id": 1, name: "bob" },
        { "id": 2, name: "billy" }
    ],
    "page": 1,
    "totalPages": 10
}