用于创建或更新资源的REST API命名约定最佳实践

Question

在我的应用程序中，客户端可以创建我们为其计算ID的资源并将其分配给该资源。

但是，客户端也可以针对每个资源引用其要使用的特定ID（我们将其称为外部ID），这样我们就不会强迫客户端仅使用我们的ID。

然后我们有以下端点：

• POST / resources /创建有效负载中带有可选external_id的资源
• PUT / resources /：id以更新资源

我们希望允许客户端使用其外部ID更新资源。我们考虑过

• PUT / resources / create_or_update /：external_id，但我们对端点名称至少说得不太满意

您是否会想到一个符合REST最佳做法的更好的名字？

Answer 1

  

您是否会想到一个符合REST最佳做法的更好的名字？

REST不在乎您对资源标识符使用什么拼写。 （演示：URL缩短程序没有破坏网络。）

如果您在两个不同的层次结构中拥有资源-一个拥有完全的拼写自治权，另一个拥有客户的控制权，那么...

/09bce7a1-1f00-4bb4-8f72-8f642295a73e/:id
/8f3b9dc8-90de-48c5-aa96-a3f5a8d8e8ee/:external_id

...很好。

您可以为层次结构中的路径选择任何喜欢的语义拼写。

由于REST无关紧要，因此您需要在其他地方寻求指导。本地编码约定是一个很好的起点-但是您可能不会问您是否已经有这样的东西要咨询。也许行销？也许他们可以从中赚钱

/bronze/:id
/superUltraPlatinumPlus/:external_id

Answer 2

所以最后我们决定去

PUT /resources/by_external_id/:external_id

这是我们根据客户参考来更新资源的“最差选择”。虽然仍然可以使用我们的参考来更新资源：

PUT /resources/:id

作为答案的建议，我们确实可以争取

PUT /resources/:external_id
PUT /resources/:id

但是，由于external_id和id可能使用相同的格式（UUID），因此可能会影响我们的性能（首先检查该值是否不作为id存在，如果是，则检查它是否可以是external_id）。

在其中的一条注释中也建议使用该变量，但我们不想使用查询参数。