在RESTful CRUD API中处理ID

Question

我正在设计一个Create / Read / Update / Delete公共Web API端点，在JSON上使用基于HTTP的RESTful模式和JSON负载，并且想知道一个设计问题必须非常普遍，但是我却很难找到指导。

让我们仅关注API的“读取”和“更新”部分。 当涉及到处理ID时，我对当前的“适当的” REST最佳实践感到有些困惑。 这就是我的意思：

通过HTTP GET“读取”员工将返回一个或多个“小部件” JSON对象（例如，我有一种方法来检索满足特定条件的所有小部件）。 每个窗口小部件对象都有一个ID字段，它是一个GUID。

我看到“更新小部件”端点的几个设计选项：

1. HTTP PUT到整个小部件对象的/ api / widgets / {widget-id}。 如果存在对象中的“ ID”字段，则API将失败 。 （我不喜欢这种方法，因为未经修改，无法将来自“读取”端点的数据往返到“更新”端点）
2. HTTP PUT到整个小部件对象的/ api / widgets / {widget-id}。 如果存在，API将忽略对象中的“ ID”字段。 （我认为它比上述方法要好，但是提供的ID可能不正确，并且我认为静默忽略不良数据是错误的）
3. HTTP PUT到整个小部件对象的/ api / widgets / {widget-id}。 API将验证对象中的ID字段必须与 URI 中的ID 匹配 ，否则将失败。 （我认为这甚至更好，但是数据仍然在URI和消息正文之间重复）
4. HTTP PUT到整个小部件对象的/ api / widgets / {widget-id}。 API将验证对象中的ID字段必须不存在或必须与 URI 中的ID 匹配 ，否则将失败。 （这是我倾向于的方法）
5. HTTP PUT到整个窗口小部件对象的/ api / widgets ，包括ID字段-即要更新的对象的ID将来自消息正文而不是URI。
6. 与＃5相同，但具有HTTP POST-如果指定了ID，则可能具有“ Update”语义，如果未指定，则可能具有“ Create”语义。

我可以在这里看到各种折衷。 选项6对我来说似乎特别优雅，但对“ RESTful”而言却不是特别好，对于API用户来说可能是一个陌生的模式。 我见过的大多数API设计指南文档似乎都建议使用“ PUT到/ api / widgets / {widget-id}”方法，但对上面＃1/2/3/4的区别却保持沉默。

那么“ REST完全正确” /最佳实践方法是什么？ （对于使用我的公共API终结点的开发人员来说，这是最熟悉且最不会混淆的事情）。 还有我在这里没有想到的其他设计选项（或设计注意事项）吗？

Answer 1

如果绝对必须提供ID，则可以将其公开。 另一种方法是，您可以在实体中具有唯一字段。 在不传递ID的情况下，您也可以创建一个包含唯一字段的DTO。 在您的情况下，{widget-id}是唯一的，并且该ID始终是自动生成的int的ID。 使用POST，这是您使用公共API的最佳方法。

如果需要对窗口小部件进行多个操作，请使用“窗口小部件”（示例：site.com/widget）创建4个不同的端点，这些端点定义了get，post，put和delete作为不同的方法。 这意味着单个API会根据调用它的不同方法而有不同的功能。