Question

I have a REST service that returns a list of objects. Each object contains objectcode and objectname.

This is my first time building a REST service, so I’m not sure how to format the response.

Should it be:

{
    "objects": {
        "count": 2,
        "object": [
            {
                "objectcode": "1",
                "objectname": "foo"
            },
            {
                "objectcode": "2",
                "objectname": "bar"
            },
            ...more objects
        ]
    }
}

OR

 [
    {
        "objectcode": "1",
        "objectname": "foo"
    },
    {
        "objectcode": "2",
        "objectname": "bar"
    },
    ...more objects
]

I realize this might be a little subjective, but which would be easier to consume? I would also need to support XML formatted response later.

Answer 1

They are the same to consume, as a library handles both just fine. The first one has an advantage over the second though: You will be able to expand the response to include other information additional to the objects (for example, categories) without breaking existing code.

Something like

{
    "objects": {
        "count": 2,
        "object": [
            {
                "objectcode": "1",
                "objectname": "foo"
            },
            {
                "objectcode": "2",
                "objectname": "bar"
            },
            ...more objects
        ]
    }

 "categories": {
  "count": 2,
  "category" : [
     { "name": "some category"}
  ]
  }
}

Additionally, the json shouldn’t be formatted in any way, so remove whitespace, linebreaks etc. Also, the count isn’t really necessary, as it will be saved while parsing the objects themselves.