Rest URL中名词与动词之间的混淆

Question

我在互联网上研究了关于 url 模式中的名词而不是动词的 restful API，但现在我看到多个链接在 URL 中使用动词。

这是一个例子。

• POST /v1/payments/authorization//capture
• POST /v1/payments/authorization//void
• POST /v1/payments/authorization//reauthorize

这是 Paypal api。 PayPal API

在 HTATEOAS 页面上的维基百科上，他们也举了一个例子；

<?xml version="1.0"?>
<account>
   <account_number>12345</account_number>
   <balance currency="usd">100.00</balance>
   <link rel="deposit" href="/account/12345/deposit" />
   <link rel="withdraw" href="/account/12345/withdraw" /> 
   <link rel="transfer" href="/account/12345/transfer" />
   <link rel="close" href="/account/12345/close" />
 </account>

链接：维基HATEOAS

谁能帮我弄清楚这一点？为什么 'capture'、'void'、'deposit'、'withdraw'、'close' 在 URI 中，因为它们都是动词而不是名词？

或者在rest-full apis url中使用这些词可以吗？

Answer 1

来自REST API Design Rulebook 的一些关于不同资源类型的sn-ps：

文档

文档资源是一个类似于对象实例或数据库的单一概念 记录。

示例： http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet

收藏

集合资源是服务器管理的资源目录。客户可以提出 要添加到集合中的新资源。但是，这取决于收藏品的选择 是否创建新资源。

例如：http://api.soccer.restapi.org/leagues/seattle/teams

商店

存储是客户端管理的资源存储库。存储资源让 API 客户端放置 资源，将它们取出，并决定何时删除它们。就他们自己而言，商店 不创造新资源；因此商店永远不会生成新的 URI。相反，每个 存储的资源有一个 URI，该 URI 由客户端在最初放入 商店。

示例：PUT /users/1234/favorites/alonso

控制器

控制器资源对程序概念进行建模。控制器资源就像可执行函数，有参数和返回值；输入和输出。

与使用 HTML 表单的传统 Web 应用程序一样，REST API 依赖于控制器 执行无法在逻辑上映射到的特定于应用程序的操作的资源 标准方法之一（创建、检索、更新和删除，也称为 CRUD）。

控制器名称通常显示为 URI 路径中的最后一段，没有子 在层次结构中跟随它们的资源。

示例：POST /alerts/245743/resend

根据书中的定义，您发布的 URI 可能属于 Controller 资源类型，本书稍后指出：

规则：控制器名称应使用动词或动词短语

例子：

• http://api.college.restapi.org/students/morgan/register
• http://api.example.restapi.org/lists/4324/dedupe
• http://api.ognom.restapi.org/dbs/reindex
• http://api.build.restapi.org/qa/nightly/runTestSuite

---

其他命名规则，只是为了完整性

• 规则：文档名称应使用单数名词
• 规则：集合名称应使用复数名词
• 规则：商店名称应使用复数名词

Answer 2

诀窍是让它成为所有与 CRUD 动词一起操作的名词（或实体）。

所以不是;

POST /v1/payments/authorization/<Authorization-Id>/capture
POST /v1/payments/authorization/<Authorization-Id>/void
POST /v1/payments/authorization/<Authorization-Id>/reauthorize

这样做；

capture -> POST /v1/payments/authorization/
void    -> DELETE /v1/payments/authorization/<Authorization-Id>
reauthorize -> delete first then capture again.

Answer 3

在 REST 中，动词是 HTTP 方法。在您的示例中，它是 POST，但也可以是 GET、PUT 或 DELETE。

名词是由 URL 标识的资源。在您的示例中，“名词”是/v1/payments/authorization/<Authorization-Id>/capture 等。

如您所见，这并不是一个真正的名词，因为capture 是一个动词：捕获支付授权。这不是 RESTful，因为它是一个命令、一个动词，而不是一个事物、一个名词。

更好的方法是将这些命令建模为/v1/payments/authorization/<Authorization-Id>/capturecommand 之类的东西。这个命令将是一个事物，一个名词。它可以有状态，例如它是否成功，结果是什么等。

有很多代码声称是 RESTful 的，但实际上并非如此。