REST API: конфликты имен конечных точек и префиксы / пространства имен / логические области в путях конечных точек

Question

Обычно я выставляю конечные точки следующим образом:

/api/1/users
/api/1/users/{uid}
/api/1/groups
/api/1/groups/{gid}
/api/1/items
/api/1/items/{iid}

Для представления иерархии я обычно go следующим образом:

/api/1/groups/{gid}/users
/api/1/users/{uid}/items

Или чтобы получить аналогичные результаты:

/api/1/users?group_id={gid}
/api/1/items?user_id={uid}

Все идет хорошо, если вы не столкнетесь с этим:

/api/1/users
/api/1/groups   # groups of users
/api/1/items
/api/1/groups   # groups of items

Здесь я могу представить 2 варианта:

1. Чтобы изменить имя конечной точки:

   /api/1/users
   /api/1/groups
   /api/1/items
   /api/1/item_groups
   

2. Чтобы изменить путь, добавив некоторый префикс, пространство имен или область:

   /api/1/{users_prefix}/users
   /api/1/{users_prefix}/groups
   /api/1/{items_prefix}/items
   /api/1/{items_prefix}/groups
   

Я предпочитаю префиксы, потому что они делают отношения между элементами немного больше visible.
С другой стороны, такие конфликты довольно редки, а префиксы усложняют путь.

Также у меня есть сомнения, потому что / api / 1 / {items_prefix} не представляет никаких ресурсов или коллекций.
Хотя / api также не представляет, и обычно путь начинается с / api / {version}.

Итак, я не могу понять, как лучше всего разрешать конфликты имен с точки зрения принципов или лучших практик REST?

Заранее спасибо.

Answer 1

Обычный отказ от ответственности: REST не заботится о структуре вашего URL-адреса, и здесь нет стандартных принципов. Далее следует более или менее предложение / мнение:

Насколько я понимаю из вашего вопроса:

1. Есть 3 основных концепции, элементы, пользователи и группы.
2. Вы хотите иметь возможность получать списки всех элементов, всех групп, всех пользователей
3. Вы хотите видеть элементы на группу и элементы на user.

Исходя из этого, я бы, вероятно, выбрал такую ​​структуру, как:

# users

/user           - list of users
/user/{id}      - one user
/user/{id}/item - items belonging to 1 user

# groups

/group           - list of groups
/group/{id}      - one group
/group/{id}/item - items belonging to 1 group
/group/{id}/user - users belonging to one group

# items

/item       - list of all items. If this is meaningless, just throw a
              useful error that tells the developer why there is no root
              collection for this.
/item/{id}  - one item