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

时间:2018-06-29 09:22:00

标签: rest api-design specifications

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

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

然后我们有以下端点:

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

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

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

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

2 个答案:

答案 0 :(得分:2)

  

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

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

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

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

...很好。

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

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

/bronze/:id
/superUltraPlatinumPlus/:external_id

答案 1 :(得分:0)

所以最后我们决定去

PUT /resources/by_external_id/:external_id

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

PUT /resources/:id

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

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

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

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