Какой URL описывает ресурс лучше?

Question

/competitions/1/clubs/5/players
/players/search?club_id=5
/players?club_id=5

Когда я должен использовать первоклассный URL для ресурса, и когда я должен использовать вложенный URL?

Обновление 1

Спасибо за ответы до сих пор. Я постараюсь прояснить ситуацию немного дальше.

Конкуренция и клуб имеют отношения многие ко многим. Клубы могут участвовать в нескольких соревнованиях. Я думаю, это сделало бы клуб первоклассным юридическим лицом, поэтому, например, способ получить доступ к клубу:

/clubs/33

Но мне также нужно иметь возможность посещать клубы, которые участвуют в определенных соревнованиях, поэтому мне тоже нужно что-то вроде этого:

/competitions/2/clubs

Но кто-то упомянул, что не рекомендуется делать ресурс доступным через несколько URI. Разве это не нарушает это?

Кроме того, я предполагаю, что такой URI не будет предпочтительным:

/competitions/2/clubs/33/players/5

Но лучше используйте это:

/clubs/33/players/5

Клуб имеет отношения один-ко-многим с Игроком.

Answer 1

/competitions/1/clubs/5/players

Поскольку URI является идентификатором отдельного ресурса, я бы сказал, что общее правило состоит в том, что если это объект, он получает «первоклассный URL».

Я склонен использовать параметры запроса только при ограничении / фильтрации списков, например, /competitions/1/clubs/5/players?gender=MALE.

Answer 2

Я бы не стал вводить идентификационные номера в URL. Они что-то значат только для тех, кто действительно знает, что они имеют в виду, но для всех остальных это бессмысленные числа.

Вы всегда должны выбирать описательные и связанные слова для своего URL, потому что этот URL-адрес способствует предоставлению информации о связанном ресурсе.

Вместо использования бессмысленных идентификационных номеров выберите уникальное имя, представляющее название команды или соревнования, например

/competitions/worldcup/clubs/usa/players

Но если вам действительно необходимо отправить анонимные данные такого рода в URL-адресе, я бы предпочел видеть их в запросе.

Использовать только значимый текст для URL.

Answer 3

Я использую элементы пути, если отношение «чувствует» дерево / директорию (как в клубе есть игроки /clubs/berlin/players). Параметры - это больше "тегов", я часто использую их для поисковых фильтров (например, защитники клуба 'berlin' с возрастом старше 22 * ​​1002 *).

Я разрабатываю структуру URL по значению домена. Самые основные понятия должны идти в корень. Если возможно, не углубляйтесь в структуру URL, я стараюсь не дублировать или создавать коллекции псевдонимов, которые представляют идентичные ресурсы (затраты на обслуживание в коде + документация удваиваются).

Вообще говоря / root, как корень, выглядит более естественно: /clubs/{club_id}/players

Я бы выставлял игроков только через /competitions/{comp_id}/clubs/{club_id}/players, если набор игроков отличается от /clubs/{club_id}/players, например во время соревнования несколько игроков заблокированы или не попали в состав команды.

Что вы имеете в виду под /competitions? Это турнир или одиночный матч? Если в одном матче с двумя клубами, возможно, используются домены + выездные домены: /competitions/{comp_id}/home-club /competitions/{comp_id}/away-club.

Обновление-1 Ответ

Вот мои мысли по поводу вашего обновления-вопроса:

Я думаю, /competitions/2/clubs - это подмножество /clubs, не каждый клуб участвует в каждом соревновании. Так что оба ресурса разные, так что два URL-адреса хороши.

Снова подумать /competitions/2/clubs/33/players/5 тоже должно быть хорошо (но важно, чтобы в сервере избегалось дублирование кода). Этот URL-адрес должен быть даже обязательным, если возвращаемый ресурс имеет подмножество /clubs/33/players (например, игроки получили травмы или был достигнут предел размера команды для конкретного соревнования).