Это может сводиться к предпочтениям, но я бы добавил, что на самом деле речь идет об организации URL логическим способом, который имеет смысл, используя существительные и действия.Так что на самом деле речь идет о наиболее интуитивном и разумном представлении о том, как работают ваши данные при соблюдении передовых методов и соглашений.
Итак, давайте рассмотрим ваши примеры.
http://<url>:<port>/api/valuation/<policy number>/<start date>
Когда я смотрю на это, мне кажется, что это представляет данные так, что существует несколько страховых полисов с одинаковым номером полиса, и вы хотите отфильтровать их до одного с указанием даты начала.Я не уверен, как выглядят ваши данные или всегда должен быть один действительный страховой полис с указанным номером полиса, но для меня это не имеет большого смысла.
http://<url>:<port>/api/valuation/<policy number>
Этопредлагает мне, что есть один страховой полис с учетом номера полиса.Это выглядит как наиболее вероятный сценарий, поэтому я начну с этого сценария 1.
Сценарий 1
Если вы знаете, что будете действовать по одному действующему страховому полису, учитываяномер политики, тогда не имеет смысл иметь дату начала в URL.Вы будете хотеть это в данных ПОЧТЫ, которые Вы получаете через тело, потому что Вы будете действовать на том единственном страховом полисе.# 2 - ваша ставка в этом случае, и вы захотите сделать множественную оценку "1020".
Ваши URL будут выглядеть примерно так:
# returns all insurance policies`
GET "http://<url>:<port>/api/valuations"
# returns one insurance policy with given policy number
GET "http://<url>:<port>/api/valuations/<policy number>"
# acts upon the insurance policy with that number, very broad
PUT "http://<url>:<port>/api/valuations/<policy number>"
# acts upon the insurance policy with number but in a more specific way with a dedicated method
# start date would be in your post that you would then bind to a view model
PUT "http://<url>:<port>/api/valuations/<policy number>/startdate"
Сценарий2
Если вы знаете, что по номеру страхового полиса вы будете получать более одного страхового полиса, и хотите отфильтровать его по дате начала, то будет целесообразно указать его в URL-адресе.URL будет выглядеть примерно так:
PUT http://<url>:<port>/api/valuations/<policy number>/startdate/<start date>
Почему?Потому что вы действуете на одном страховом полисе из списка страховых полисов с тем же номером страхового полиса с разными датами начала.
Таким образом, ваши URL будут выглядеть примерно так:
# returns all valuations insurance policies`
GET "http://<url>:<port>/api/valuations"
# returns list of insurance policies with the same policy number
GET "http://<url>:<port>/api/valuations/<policy number>"
# return one insurance policy with the policy number and start date
GET "http://<url>:<port>/api/valuations/<policy number>/startdate/<start date>"
# updating information for that ONE policy with policy number and start date
PUT "http://<url>:<port>/api/valuations/<policy number>/startdate/<start date>"
Я основываю свой ответ на URL-адресах, основанных на существительных, а не на глаголах.Подробнее об этом: Путаница между существительным и глаголом в URL-адресах остальных
Если вы передаете начальную дату в качестве параметра
POST, вероятно, она должна быть привязана кпросмотр модели:
class ValuationPolicyStartDateViewModel
{
public DateTime? StartDate { get; set; }
}
// then in your controller
// PUT StartDate = "01/22/2018" will then be bound to your view model
public IHttpActionResult UpdatePolicyByStartDate(string policyNumber, [FromBody] ValuationPolicyStartDateViewModel viewModel)
{
... code that validates etc ...
}
TL; DR
Если /api/valuation/<policy number> возвращает 1 страховой полис, перейдите к варианту 2 в своих примерах и сделайте множественное "оценка".
Если /api/valuation/<policy number> возвращает более 1 страхового полиса, вам следует сделать пару вещей: изменить valuation на valuations и добавить startdate в качестве переменной фильтра.