Оба представления полезны.Я использовал единственное число для удобства довольно долгое время, перегиб может быть трудным.Мой опыт в разработке строго единичных API REST: разработчики, использующие конечную точку, не уверены в том, какой может быть форма результата.Теперь я предпочитаю использовать термин, который наилучшим образом описывает форму ответа.
Если все ваши ресурсы находятся на верхнем уровне, то вы можете обойтись без единственного представления.Избегать перегиба - большая победа.
Если вы используете какие-либо глубокие ссылки для представления запросов по отношениям, тогда разработчикам, пишущим против вашего API, может помочь более строгое соглашение.
MyСоглашение состоит в том, что каждый уровень глубины в URI описывает взаимодействие с родительским ресурсом, а полный URI должен неявно описывать то, что извлекается.
Предположим, у нас есть следующая модель.
interface User {
<string>id;
<Friend[]>friends;
<Manager>user;
}
interface Friend {
<string>id;
<User>user;
...<<friendship specific props>>
}
Если бы мне нужно было предоставить ресурс, позволяющий клиенту получить менеджера конкретного друга определенного пользователя, он мог бы выглядеть примерно так:
GET /users/{id}/friends/{friendId}/manager
Вот еще несколько примеров:
GET /users
- список пользовательских ресурсов в глобальной коллекции пользователей POST /users
- создание нового пользователя в глобальной коллекции пользователей GET /users/{id}
- получить конкретного пользователя из глобальной коллекции пользователей GET /users/{id}/manager
- получить менеджера определенного пользователя GET /users/{id}/friends
- получитьсписок друзей пользователя GET /users/{id}/friends/{friendId}
- получить конкретного друга пользователя LINK /users/{id}/friends
- добавить ассоциацию друзей к этому пользователю UNLINK /users/{id}/friends
-удалить ассоциацию друзей у этого пользователя
Обратите внимание, как каждый уровень отображается на родителя, на которого можно воздействовать.Использование разных родителей для одного и того же объекта нелогично.Извлечение ресурса на GET /resource/123
не оставляет никаких указаний на то, что создание нового ресурса должно быть сделано на POST /resources