在RESTful CRUD API中处理ID

Question

我正在设计一个公共的Web API端点，使用基于HTTP的RESTful模式和JSON负载，实现创建/读取/更新/删除功能，并且我想询问一个设计问题，这个问题可能非常普遍，但我很难找到指导方针。

让我们只关注API的“读取”和“更新”部分。当处理ID时，我有些困惑当前的“适当”REST最佳实践。下面是我的意思：

通过HTTP GET“读取”员工将返回一个或多个“widget”JSON对象（例如，我有一种方法可以检索满足某些条件的所有widget）。每个widget对象都有一个ID字段，它是一个GUID。

对于“更新widget”端点，我看到了几种设计选项：

1.将整个widget对象作为HTTP PUT发送到/api/widgets/{widget-id}。如果对象中存在“ID”字段，则API将失败。(我不喜欢这种方法，因为从“读取”端点获取的数据无法在不修改的情况下传递到“更新”端点)

2.将整个widget对象作为HTTP PUT发送到/api/widgets/{widget-id}。如果存在，则API将忽略对象中的“ID”字段。(我认为这比上面的做法好，但提供的ID可能是不正确的，而且我认为默默地忽略错误数据是错误的)

3.将整个widget对象作为HTTP PUT发送到/api/widgets/{widget-id}。API将验证对象中的ID字段必须与URI中的ID匹配，否则将失败。(我认为这更好，但数据仍在URI和消息正文之间重复)

4.将整个widget对象作为HTTP PUT发送到/api/widgets/{widget-id}。API将验证对象中的ID字段必须不存在或必须与URI中的ID匹配，否则将失败。(这是我倾向的方法)

5.将包括ID字段在内的整个widget对象作为HTTP PUT发送到/api/widgets，即要更新的对象的ID将来自消息正文而不是URI。

6.与第5种相同，但使用HTTP POST - 如果指定了ID，则可能具有“更新”语义，如果没有，则可能具有“创建”语义。

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

那么如何以“符合RESTful标准”/最佳实践的方式来做到这一点呢？（这样做对于使用我的公共API端点的开发人员来说应该是最熟悉和最不容易混淆的）。此外，还有其他设计选项（或设计考虑）我没有考虑到吗？

- Eugene Osovetsky

Answer 1

如果ID是必须的，那么可以将其公开。另一种方法是，在实体中添加一个唯一字段。不传递ID，可以创建一个包含唯一字段的DTO。在您的情况下，{widget-id}是唯一的，而id始终是int类型的自动生成的ID。使用POST，这是公共API的最佳方法。

如果需要对小部件执行多个操作，请创建4个不同的端点，其中“Widget”（例如：site.com/widget）定义了get、post、put以及delete作为不同的方法。这意味着单个API将根据调用它的不同方法而具有不同的功能。

- RakhuNathan