Как правильно построить URL в идеологии REST?

Question

[Дмитрий Лабутин]

Разрабатываю REST API.
Суть простая.
1. Есть поставщики (много)
2. Есть расчет цены за услугу у каждого поставщика (услуга у поставщика одна). Стоимость зависит от размера объекта, который будет передаваться параметром.

Вариант номер 1:
/providers/ - вывод информации о всех поставщиках (ID, название, описание и т.п.)
/providers/provider_id - вывод информации только об одном конкретном поставщике
/providers/provider_id/price?size=123 - вывод стоимости услуги конкретного поставщика (например, стоимость покраски объекта размером 123 поставщиком provider_id)
Все бы хорошо, но хочется сделать запрос, чтобы вывелись цены сразу ВСЕХ поставщиков за покраску объекта размером 123. Получается, что нужно добавить еще:
/prices/?size=123 - на выходе будут цены от всех поставщиков услуги

Вариант номер 2:
/providers/ - вывод информации о всех поставщиках (ID, название, описание и т.п.)
/providers/provider_id - вывод информации только об одном конкретном поставщике
/prices/provider_id?size=123 - - вывод стоимости услуги конкретного поставщика (например, стоимость покраски объекта размером 123)
/prices/?size=123 - на выходе будут цены от всех поставщиков услуги

По сути, тут отличие вариантов только в одном URL.

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

Или может быть я вообще в корне неправильно строю маршрутизацию с точки зрения идеологии REST API?

Comments

[Дмитрий]

А на кого расчитывается API? На работов или на людей?

[Дмитрий]

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

Answer 1

[Дмитрий]

Может поможет:
* pyvideo.ru/video/87/python-rest-api
* thenextcode.ru/post/10-kak-pravilno-delat-rest-api...
* habrahabr.ru/post/38730

Насколько я понял выигрывает тот API, что содержит:
* версию
* существительные
* Стремится не содержать глаголов

GOOD:
super-puper-api/ver1/resource

BAD:
super-puper-api/getResources

Comments

[DevMan]

версия не обязательно должна быть указана в урле

[Дмитрий]

DevMan: Не обязательно. Но в URI это 1. удобнее всего 2. Нагляднее

[Дмитрий Лабутин]

Версию да, планирую добавить. Не стал приводить, чтобы не сбивать с сути вопроса :)

Answer 2

[Adam_Ether]

Первый вариант мне нравится больше.
Но в нем есть скользкий момент:
/providers/provider_id/price?size=123
Получается, что это частный случай /providers/provider_id, а нового ресурса "prices" как такого нет, это просто атрибут провайдера, поэтому предлагаю использовать /providers/provider_id с фильтрами как по полям, так и по значениям
пример: /providers/provider_id?fields=id,prices&data=123

Вообще советую почитать
Oreilly.REST.API.Design.Rulebook

Comments

[Дмитрий]

Adam_Ether Большущее Вам спасибо за то что сказали о существовании такой книги! ;)

Answer 3

[Станислав Романов]

1 вариант полностью правильный.

Добавлю что выборку по цене и конкретному поставщику можно сделать еще и так

/prices/?size=123&provider_id=1

jsonapi.org в помощь.