PUT 查询字符串的正确格式如何？

Question

我需要构建一个 PUT 方法，该方法将接收保险单号和相关期间的星号。这个方法会更新开始相关的时间段，所以既然有更新，这个方法就被定义为一个PUT动词。

我的方法的正确格式是什么？我对两种可能的正确格式感到困惑：

http://<url>:<port>/api/valuation/<policy number>/<start date>

或

http://<url>:<port>/api/valuation/<policy number>

并从正文接收日期？

在这两种情况下，我如何声明路由（我使用的是 .net framework 4.5）

对于选项#1

[Route("UpdatePeriod/{numPolicy}/{startDate}")]
public IHttpActionResult UpdatePeriod(string numPolicy, string startDate)

对于选项 #2

[Route("UpdatePeriod/{numPolicy}")]
public IHttpActionResult UpdatePeriod(string numPolicy, [fromBody] string startDate)

谁能给我一个提示？我对此有点迷茫。

提前致谢。

Answer 1

这可能归结为偏好，但我要补充的是，它实际上是关于以合理的方式组织 URL，使用名词和动作是有意义的。因此，它实际上是在遵循最佳实践和惯例的同时，以最直观、最合理的方式呈现您的数据工作方式。

让我们看看你的例子。

http://<url>:<port>/api/valuation/<policy number>/<start date>

当我看到这个时，在我看来，这表示存在多个具有相同保单编号的保险单的数据，并且您希望通过提供的开始日期将其过滤为一个。我不确定您的数据看起来如何，或者是否应该始终有一份有效的保单给定保单编号，但这对我来说没有多大意义。

http://<url>:<port>/api/valuation/<policy number>

这向我表明，给定保单编号，只有一份保险单。这似乎是更有可能发生的情况，所以我将从第 1 种情况开始。

场景 1

如果您知道您将根据一份给定保单编号的有效保单采取行动，那么在 URL 中包含开始日期将不有意义。您会希望它出现在您通过身体获得的 POST 数据中，因为您将根据该一份保险单行事。在这种情况下，#2 是你的赌注，you'll want to make "valuation" plural。

你的 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>"

我的答案基于基于名词的 API url，而不是基于动词。 更多信息：Confusion Between Noun vs. Verb in Rest URLs

---

如果您将开始日期作为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 作为过滤变量。