RESTful API: как моделировать представление JSON?

Question

Я разрабатываю RESTful API для приложения бронирования. Вы можете запросить список гостиниц. И вот где я действительно не знаю, как спроектировать представление JSON. Это мое XML-представление:

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

Моя первая попытка преобразовать это в JSON привела к следующему выводу (1):

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

Но когда я посмотрел, как это делают другие API, я обнаружил нечто похожее на это (2):

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

Я знаю, что версия 1 - это объект, а версия 2 - массив.

Но какой из них лучше в этом случае?

Answer 1

Вы можете смоделировать JSON следующим образом:

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

и вы можете вернуть это на GET http://example.org/accomodations Затем можно создать новое помещение через POST http://example.org/accomodations с чем-то вроде следующего в теле:

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

Answer 2

Палка с номером 2.

Не моделируйте вывод JSON после версии XML.

Каждый существующий API использует представления с массивами. Большинство библиотек синтаксического анализа возвращают экземпляры, похожие на списки, которые позволяют очень легко управлять всеми объектами, которые они содержат.

Номер 1 является действительным JSON, но это не то, чего ожидает большинство ваших разработчиков.

Answer 3

Если вы собираетесь использовать ключ (1, 2, ...) в качестве идентификатора при обмене данными с сервером, лучше использовать словарь, иначе я бы выбрал массив.Тогда уникальный идентификатор, вероятно, является полем в записи.