RESTful API: How to model JSON representation?

Question

I am designing a RESTful API for a booking application. You can request a list of accommodations. And that's where I don't really know how to design the JSON represenation. This is my XML representation:

<?xml version="1.0" encoding="utf-8"?>
<accommodations>
    <accommodation>
        <name>...</name>
        <category>couch</category>
    </accommodation>
    <accommodation>
        <name>...</name>
        <category>room</category>
    </accommodation>
<accommodations>

My first try to convert this to JSON resulted in this output (1):

{
    "0": {
        "name": "...",
        "category": "couch"
    },
    "1": {
        "name": "...",
        "category": "room"
    }
}

But as I looked how others APIs did it, I found something looking more like this (2):

[
    {
        "name": "...",
        "category": "couch" 
    },
    {
        "name": "...",
        "category": "room" 
    }
]

I know version 1 is an object, and version 2 an array.

But which one is better in this case?

Answer 1

You could model the JSON as follows:

{
  "accomodations" : [
    {
      "accomodation" : {
        "name": "...",
        "category": "couch",
        "uri": "http://example.org/accomodations/accomodation_1"
      }
    },
    {
      "accomodation": {
        "name": "...",
        "category": "room",
        "uri": "http://example.org/accomodations/accomodation_2"
      }
    }
  ]
}

and you could return this on a GET http://example.org/accomodations Creating a new accomodation could then be done through a POST http://example.org/accomodations with something like the following in the body:

{
  "accomodation": {
    "name": "...",
    "category": "room"
  }
}