Question

我正在创建一个API，该API将允许用户创建，更新和删除博客文章。现在我想为博客文章创建一个更新处理程序，但是为这个调用创建一个模型让我开始思考。

对于PUT请求，应该将要更新的博客的id放在URI内还是正文内，如下所示：

在URI中：

/api/blog/23

体内：

{
  "id": "23",
  "title": "new blog title"
}

对与错吗？如果没有，那么RESTful api通常遵循的惯例是什么？

Answer 1

从技术上讲，没有正确或错误的方法来设计API。但是，精心设计的API会更容易理解。

假设这是一个REST API，我希望保持一致。如果您的API要求URI中的GET资源有一个ID，那么我的建议是保持与PUT的URI中的ID一致。

Microsoft有不错的API design guidance文章，也建议保持URI一致。

Answer 2

PUT在HTTP中表示非常特定的内容

PUT方法请求创建目标资源的状态或将其替换为由请求消息有效负载中包含的表示形式定义的状态。

这是一个请求，要求服务器更改服务器副本以匹配客户端提供的表示形式。考虑“保存”或“覆盖”-一种内容管理操作。

因此，如果此博客文章的JSON表示形式应为id，标题，别无其他-那么就可以了。

如果您打算更改标题，而其余的表示形式保持不变，则您需要（a）发送整个表示形式，包括您的编辑，或者（b）选择一个具有不同语义的方法（POST或PATCH可能有意义）。

URI是一个标识符-哈希表/字典中的思考键。没有特别的原因，编码到标识符中的数据需要与表示中的数据匹配。当然可以-我们经常将其编码为服务器将在其内部实现中使用的URI信息-但/4ca7fce6-efce-42d1-8fc6-666c3cae4f90是资源的完美有效标识符。