Правильный шаблон маршрута для коллекций RESTful с дополнительными ресурсами

Question

Я делаю RESTful API совсем немного (выставляя и потребляя третьи стороны), и я вижу два следующих шаблона, которые появляются здесь и там. У каждого есть плюсы и минусы, и ни один из них не является «чистым», на мой взгляд.

Итак, ситуация: у вас есть ресурс коллекции (например, «активы»), и вы хотите выставить дополнительные ресурсы в коллекции (например, субресурсы самой коллекции, а не актива, такие как агрегированная конечная точка представления или некоторые команды).

Две модели я вижу, являются:

1. Люди создают RESTful коллекции ресурсов, как /assets/${asset-id} и выставить все остальное им нужно как GET /assets/owned, GET /assets/summary, POST /assets/recheck-inventory. Это выглядит аккуратно и кратким, но вводит столкновение между ${asset-id} и существительными URL-адресов подресурсов (например, asset12345 и summary находятся на том же месте в URL-адресе).

2. Другие делают /assets/items/${asset-id} и выставляют все, как GET /assets/owned, GET /assets/summary и так далее. Это более чистое из перспективы маршрутизации и немного более надежное будущее, но добавляет дополнительное существительное в маршрут, что приводит к путанице, когда люди пытаются сделать POST /assets, например.

Рекомендации по «лучшей практике», которые я прошел, до сих пор полностью избегают вопроса. Я также понимаю, что REST - это конвенция, а не стандарт, и есть универсальный ответ «это зависит». Тем не менее, я чувствую, что здесь должна быть общая рекомендация.

Следовательно, возникает вопрос: какой из двух вы бы использовали?

UPDATE: выяснить, давайте предположим, что:

• /assets/owned содержит объекты различных типов, а не активов, так что это не запрос, и вы можете GET/POST/DELETE элементов в нем.
• /assets/summary представляет собой совокупность документов (например, отчет с величинами, например)
• /assets/recheck-inventory является командой (т.е. POST только)

Кроме того, мы хотим придерживаться принципов REST:

• маршрут маршрута должен идентифицировать объект и его состояние однозначно.
• параметры запроса изменяют, какие элементы возвращаются, но не изменяют формат полезной нагрузки.
• заголовки для информации на уровне протокола и не меняют логику службы (т.е. представление, безопасность, кэширование и т.д.)

Answer 1

Я не люблю эти подходы либо, но быть в курсе, что REST не поставить ограничение на то, как создать структуру URI, чтобы вы могли делать все, что считаете правильным. По-видимому, разработчики этих веб-сервисов правильно поняли этот подход.

Я бы сделал что-то вроде следующего с вашими URI, так как мне нравятся плоские URI намного лучше.

/assets/items/${asset-id} 
    -> /assets/${asset-id} 
/assets/owned 
    -> /assets/?owned 
    -> /assets/?owned=true 
/assets/summary 
    -> /assets-summary 
    -> /assets/ + "Prefer: return=minimal" 

Вы можете узнать больше о prefer header here, но имейте в виду, что вам нужно, чтобы зарегистрировать его в vary header, если вы хотите, чтобы быть вторичным ключом кэша.