Когда использовать pathParams или QueryParams

Есть ли правило большого пальца о том, когда нужно использовать параметры пути для URL-адреса, и когда вы должны использовать параметры запроса?

Скажем, у меня есть табличный счет-фактура с полями компании (PK), InvoiceNo (PK), Invoiceline, invoiceValue, noOfLines, salesPerson

Мое настоящее мышление заключается в том, что ваш URL-адрес должен быть в строках

/Invoice/

Будет отображаться все счета-фактуры

/Invoice/{company}

Будет отображаться все счета-фактуры для компании.

/Invoice/{company}/{InvoiceNo}

Отображает этот конкретный счет-фактуру и

/Invoice/{company}/{InvoiceNo}?invoiceLineNo=23

отображается только строка 23.

Я думаю, что поля Первичного ключа должны быть частью пути, а любые другие поля, которые вы фильтруете, являются частью параметра запроса.

Это звучит как разумный способ разграничения между двумя?

Ответ 1

Мое личное правило, которое PathParam ведет к типу объекта, который вы запрашиваете.

/Invoices             // all invoices
/Invoices?after=2011  // a filter on all invoices

/Invoices/52          // by 52
/Invoices/52/Items    // all items on invoice 52
/Invoices/52/Items/1  // Item 1 from invoice 52

/Companies/{company}/Invoices?sort=Date
/Companies/{company}/Invoices/{invoiceNo} // assuming that the invoice only unq by company?

Процитировать Mr Rowe: параметры пути для группировки данных, параметры запроса для фильтрации

Ответ 2

Чтобы добавить к Gareth ответ, необязательные параметры также проще поставить в качестве параметров запроса. Обычно именно ограничения вашей серверной среды определяют, что является лучшим вариантом. Неразумно пытаться вывести слишком много семантического значения, является ли параметр параметром запроса или параметром пути. Помните, что URI непрозрачны для клиента.