Question

我正在为我们正在开发的项目设计REST API。也就是说，我正在编写将在稍后实施的规范。

我在考虑名词/资源而不是动作/动词时遇到麻烦。在没有涉及太多项目细节的情况下，我们正在围绕SVN编写API。例如，采取提交更改的操作到SVN服务器。在我们的项目中，我们有多个提交操作的定义/版本：

只需提交所有已更改的文件
提交已更改文件的列表（子集，而不是整组已更改的文件）
...

（1）您将如何设计网址？第一个问题是，如何将提交操作描述为名词/资源而不是动词？

有些人会说：

POST/PUT http://server.com/api/revision/commit

应该是POST还是PUT？我并没有真正创建提交资源，因此它不是POST。但是，我并没有真正更改提交资源，因此它不是PUT。实际上，它不是资源，它是动作。一旦执行了该动作，它就会消失，没有资源可以创建，更改或保留供以后参考。

那就是说，它必须是一个资源，所以URL应该是这样的

POST http://server.com/api/revision/commitment

这也是一个POST，因为我们正在创建一个承诺。我们没有改变任何东西，所以没有PUT。另请注意，我将 commit 更改为 commitment ，以反映我们正在处理资源的事实。

这有意义吗？对我而言，它没有，它让我疯了。我想执行一个动作，而不是创建一个类似于动作的资源。但无论如何。

那就是说，进一步说，我刚刚创建了一个承诺资源。从逻辑上讲，我应该可以在以后检索它：

GET http://server.com/api/revision/commitment/:id

但是没有承诺资源！为了成为RESTful，我被迫制作一个。 头部爆炸

那么，您如何真正指定REST API中的资源操作？我不是在谈论创建资源的行为（创建用户，......），而是谈论操纵资源或对资源采取行动的行为（提交修订，......）。

（2）然后，第二，如果是第二个定义（见上文），我们如何指定更改文件的子集？通过参数或在BODY中的某些结构（例如JSON数组）？哪一个更受欢迎？有没有一般规则？

全部谢谢！

Answer 1

有时，在URL设计中备份比继续更容易。在我看来，你所谓的“承诺”实际上是一个修订本身。 svn commit基本上意味着“请接受我目前选择的修订版中的这些差异作为新的（子）修订版”。因此，您需要确定当前选定的修订版本（为了保持无状态），然后以有意义的方式附加到它：

POST http://server.com/api/revisions/16/children/

也就是说，POST一个封装了与版本16的差异的实体。然后，服务器可以使用201 Created，以及Location: /api/revisions/23/（或/api/revisions/16/children/1，它重定向到前者）进行响应。

然后，您不仅提供了新修订的创建，而且还很可能添加了一个有用的特定修订版直接子项列表。

Answer 2

停止思考行动; D

首先让你的SVN基于文件，而不是基于数据库，这将有助于思考。

如果您考虑一下，您的存储库中只有3个restfull（实际上可能是4个）操作：svn add + svn commit将新文件放在版本控制下。这将转换为要添加和提交文件的文件夹上的PUT。 svnroot：/ project /文件夹实际上因为文件的“id”已知你实际上可以直接在文件的URL上输入：svnroot：/project/folder/file.c

您希望提交更改，该更改将转换为资源上的POST（不是文件夹，而是该文件夹中的实际现有文件）。 POST svnroot：/project/folder/file.c

如果你想删除一个文件，它是一个删除。

如果您想知道某个文件的版本号使用了STATUS。

开始考虑实际发生的事情，而不是如何调用动词（co，ci，add，update等），发生的事情是文件在存储库中“创建”，即PUT或修改，这就是POST或删除/删除的DELETE或状态被查询是STATUS。

如果你检索文件，那显然是一个GET。

所以，上面是一个实际的现有资源。现在您可以开始发明更多功能，为文件提供大小和作者或最后一个提交者或提交消息！现在您需要处理没有真实资源的URL。有人称之为虚拟资源。

只需将“/ authors”等添加到资源URL的末尾，然后使用POST添加作者和GET来阅读作者。（根据REST范例，你也可以使用PUT，也许会更干净）

在REST API中设计动作 - 什么时候RESTful太RESTful了？

2 个答案: