rest - 在 RESTful CRUD API 中处理 ID

Question

我正在设计一个创建/读取/更新/删除公共(public) Web API 端点，使用基于 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，则可能使用“更新”语义，如果未指定，则使用“创建”语义。

我可以在这里看到各种权衡。选项 6 对我来说似乎特别优雅，但不是特别“RESTful”并且可能是 API 用户不熟悉的模式。我见过的大多数 API 设计指南文档似乎都推荐“PUT 到/api/widgets/{widget-id}”方法，但对上面的 #1/2/3/4 区别只字未提。

那么“完全正确的 REST”/最佳实践方法是什么？(使用我的公共(public) API 端点的开发人员最熟悉且最不容易混淆的方法)。还有其他我没有想到的设计选项(或设计注意事项)吗？

Answer 1

如果 ID 绝对是强制性的，您可以公开 ID。另一种方法是，您可以在实体中拥有一个独特的字段。在不传递 ID 的情况下，您也可以创建一个包含 Unique 字段的 DTO。在您的情况下，{widget-id} 是唯一的，并且 id 始终是自动生成的 int id。使用 POST，这是您使用公共(public) API 时的最佳方法。

如果您需要对小部件执行多项操作，请使用“小部件”(例如:site.com/widget)创建 4 个不同的端点，这些端点将获取、发布、放置和删除定义为不同的方法。这意味着单个 API 将根据调用它的不同方法发挥不同的作用。