WebAPI2中正确的RESTful实现是什么？

Question

实际上，我发现了大量关于这个话题的意见，但没有一个能说服我哪种方法是正确的。更具体地说，我有以下几个问题：

单数还是复数或两者都可以？

• 是否有正确和错误的方法？

  标准和约定存在是有原因的，我不相信我会满足于“只是个人口味”的回答。难道没有任何指导方针或标准吗？没有完成Fieldings工作的权威机构吗？

应该返回什么IHttpActionResults？它们应该包含什么？

• Get - 返回Ok();
• Post - 返回Created();
• Put - 返回(Put? Ok?)
• Delete - 返回(Deleted? Ok?)

在Created(location)中返回什么？

假设控制器路由为“api/v1/model”，应该是

• '/{id}'？
• 'api/v1/model/{id}'？
• 'http://www.mywebapi.com/api/v1/model/{id}'？

我提出这些问题是因为我经常遇到如何最好地实现API的冲突。

- Marcus

---

+1 这是一个好问题。当你说“假设控制器路由是'api/v1/model'，它应该是什么”时，你能否详细说明一下你的意思？控制器路由始于域名（www.mywebapi.com/），那么选项2和选项3有什么区别呢？ - Marcus Höglund

Created() 方法中的 location 参数应该是对当前“项”（item）的引用，对吧？我认为 2 和 3 之间的区别就很明显了。#2 假设 API 消费者本身将提供 URL 的右侧部分，而 #3 - 将返回整个和完整的 URL。location 参数只是一个普通的字符串，据我所知，没有任何“.NET 自动完成路由到 URL 转换工具”的事情发生。 - Marcus

好的，现在我明白了。当你阅读问题时，“Created（location）”行代表它本身。你应该删除换行符或重写它们。不过这是个好问题，如果API被不同域名消费，那么我会返回完整的URL。 - Marcus Höglund

Answer 1

问题: 单数还是复数或两者都可以

永远不要同时使用两者。只能选择其中一个。使用名词而不是动词。

不要使用动词：

/获取所有汽车
/创建新车
/删除所有红色汽车

不要混淆单数和复数名词。保持简单，对所有资源仅使用复数名词。

/cars instead of /car
/users instead of /user
/products instead of /product

现在，如果您往下看，这将更加清晰：

GET /tickets - 检索票务列表
GET /tickets/12 - 检索特定票务
POST /tickets - 创建新的票务
PUT /tickets/12 - 更新票务 #12
PATCH /tickets/12 - 部分更新票务 #12
DELETE /tickets/12 - 删除票务 #12

如果资源与另一个资源相关，请使用子资源。

GET /cars/711/drivers/ - 返回车辆 711 的驾驶员列表

Q: Created(location)中返回什么？

200 OK - 成功进行 GET、PUT、PATCH 或 DELETE 操作的响应。对于不导致创建的 POST 请求也可以使用此代码。

201 Created - 创建了新资源时 POST 请求的响应。应该与指向新资源位置的Location header相结合。

请明确您最后一个问题，并我会相应地更新我的答案。

目前并没有 REST 的定义标准，每个人都根据自己的需要使用最佳实践。然而，我建议您阅读来自 apigee.com 的PDF，其中列出了 REST API 的最佳实践以及每个主要的参与者（如 Facebook、Twitter 等）使用的内容。

- Nilesh Thakkar

---

location 应该是绝对URL还是左侧URI？客户端应该期望 location 是什么？ - Marcus

另一个问题是关系（及其路由如何工作）并不总是清晰明确，考虑到多对多的关系...其中api/accounts/{id}/user可能是一个选项，但也可以是api/users/{id}/accounts，这将导致语义上陷入无限循环，在这种情况下适当的方式是 api/accounts/{id}/user/accounts/{id}/user/accounts/{id}[...]。 - Marcus

如果您参考我的帖子中的Location Header链接，它会显示绝对URI。 - Nilesh Thakkar

因为一个“账户”属于一个“用户”，而一个“用户”拥有多个“账户”，所以它是一个多对多的关系，这使得正确的方法不清楚；是accounts/{id}/user还是users/{id}/accounts。 - Marcus

我看到你大部分的想法和回复都非常有道理，我也同意它们，但是我所期望的是一套标准定义，并且我仍然看到一些架构上的不确定性。 - Marcus