REST-упаковка одного ресурса в коллекции

Question

У меня небольшая дилемма.

Если у вас есть следующие конечные точки URI:

/item
/item/{id}

Если я сделаю запрос GET на /item, я ожидаю что-то вроде этого:

<Items>
   <Item>...</Item>
   <Item>...</Item>
   ...
</Items>

Если я сделаю GET-запрос к / item / {id}, я ожидаю что-то вроде этого:

<Item>
   ...
</Item>

Некоторые из моих коллег по команде утверждают, что мы должны разработать API, поэтому, когда кто-то делает GET для / item / {id}, он должен быть возвращен как набор из одного элемента. Как это:

<Items>
   <Item>...</Item>
</Items>

Мне кажется, это неправильно. Вам это тоже кажется неправильным? Пожалуйста, объясните, почему, так что я могу убедить либо себя использовать всегда завернутую версию ресурса, либо моих коллег-разработчиков, чтобы использовать не обернутый единственный ресурс.

Answer 1

Самое главное, нет правильного и неправильного ответа на этот вопрос.

Тем не менее, вот что я думаю.

Если вы хотите вернуть один элемент, я хотел бы сделать это:

GET /Item/{Id}

=>
<Item>
  ...
</Item>

Если {Id}не существует, то сервер должен вернуть 404.

Если я хочу вернуть коллекцию элементов, я бы сделал

GET /Items
=>
<Items>
 <Item>...</Item>
 <Item>...</Item>
</Items>

Если нет элементов, то он должен вернуть200 с пустым элементом <Items/>.

Если клиенту действительно легче иметь дело с коллекцией, содержащей только один элемент, вы можете сделать что-то подобное.

GET /Items?Id={Id}
=>
<Items>
  <Item> ... </Item>
</Items>

Разница в том, что если бы {Id} не существовало, то я бы имел тенденцию возвращать 200, а не 404.

Answer 2

Мне кажется нелогичным. Вы потенциально экономите усилия на коде на стороне клиента, имея один способ чтения данных из ваших двух методов GET. Этому, конечно, противостоит наличие дополнительного кода для переноса вашего единственного метода GET в коллекцию.

Если вы хотите примеры из реального мира,

• Твиттер возвращает человека представление ресурса не завернутый в коллекцию
• базовый лагерь, ранний сторонник API на основе REST, также следует за этой моделью

РЕДАКТИРОВАТЬ: Наш API использует это Структура кода состояния HTTP

Answer 3

Я думаю, что ваши коллеги правы, если вы думаете о потребляющей стороне вашего сервиса REST, который затем может обрабатывать каждый ответ как набор. И еще одна вещь: если {id} не существует, что возвращает ваш сервис? Ничего такого? Затем потребитель должен проверить либо нулевой результат, либо ответ об ошибке, отдельный элемент или коллекцию. Согласно моему опыту, получение коллекции в любом случае (которая может быть пустой) является наиболее удобным способом обслуживания службой REST.