REST设计指南

Question

我正在为REST接口设计一个公共API。其中之一就是使用http动词，特别是删除动词。

我们希望公开启动/停止或执行/中止特定作业的方法。这两种api设计的两种风格是：

POST

http://localhost/api/campaignrun/1

使用id为1执行活动运行

删除

http://localhost/api/campaignrun/1

以id 1中止竞选活动。

或者..。

POST

http://localhost/api/campaignrun/1

{ action=execute}

使用id为1执行活动运行

POST

http://localhost/api/campaignrun/1

{ action=abort }

取消id为1的竞选活动

如果有我最喜欢的，哪一个更RESTful？

Answer 1

是否可以重新启动已停止的作业？如果是这样的话，我建议您使用POST，因为您并没有真正删除任何资源。但是，您可以更改urls以更好地指示您要实现的目标：

POST

http://localhost/api/campaignrun/1/start

和

POST

http://localhost/api/campaignrun/1/stop

因此，没有必要提供一个请求机构来说明行动的类型。

旁注:对我来说，DELETE表示竞选活动将永远取消，因此不能重新启动。因此，如果客户端试图访问资源，则返回404。

Answer 2

在您的两种设计中，I会投票给您使用POST的第二款，但只需稍作修改:使用PUT：

PUT http://localhost/api/campaignrun/1

{ action: abord }

这个API清楚地说明了它的意图:您有campaignruns (最好保留这个复数)，您想要有{id} = 1的campainrun，还有一个名为action的属性，我想要update。

这样，您的API就可以与幂等性 of http谓词保持一致：PUT应该是幂等的，POST不应该是幂等的。对于您的情况来说，这意味着，无论用户按上述请求多少次，结果都是一样的:使用id=1的竞选活动将被中止。

注意:我看到您已经接受了一个在URI中提出动词的答案，然后对它们使用POST。这篇文章不是主张或反对休息的地方，但既然你的问题是哪个设计更RESTful，你应该三思而后行。您可能需要检查这个非常好的38页免费电子书，它谈到了设计API的最佳实践。除其他外，它建议将动词排除在基本URL之外，除非很少使用。看看，这会很有帮助的！

Answer 3

第一种是更“安息”。您将面临的唯一问题是，如果您需要删除而不是中止将来运行的竞选活动。如果将来需要运行删除记录功能，则始终可以传递要删除的操作。