REST API 设计指南

Question

我正在为我们的 REST 接口(interface)设计一个公共(public) API。出现的问题之一是 http 动词的使用，特别是 DELETE 动词。

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

发布

http://localhost/api/campaignrun/1

执行 ID 为 1 的营销事件

删除

http://localhost/api/campaignrun/1

中止 ID 为 1 的事件运行

或者...

发布

http://localhost/api/campaignrun/1

{ action=execute}

执行 ID 为 1 的营销事件

发布

http://localhost/api/campaignrun/1

{ action=abort }

中止 ID 为 1 的营销事件运行

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

Answer 1

在您的两个设计之间进行选择，我会投票给您的第二个，它使用 POST，但进行了一些小修改:使用 PUT相反:

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

{ action: abord }

此 API 清楚地说明了其意图:您有 campaignruns(最好保留此复数)，您希望campainrun 的 {id} = 1，该资源有一个名为 action 的属性，我想要更新。

这样，您就可以使您的 API 与 idempotence 保持一致。 http 动词:PUT 应该是幂等的，POST 不应该。对于您的情况，这意味着，无论用户点击上述请求多少次，结果都是相同的:id=1 的事件运行将被中止。

注意:我看到您已经接受了在 URI 上提出动词的答案，然后对它们使用 POST 。这篇文章并不是支持或反对 REST 的地方，但由于您的问题是关于哪种设计更 RESTful，因此您应该三思而后行。您可能想查看这个非常漂亮的 38 页免费 ebook这谈到了设计 API 的最佳实践。其中，它建议将动词排除在基本 URL 之外，除非极少数情况。检查一下，这会很有帮助!