rest - Rest URL 中名词与动词的混淆

Question

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

这是一个例子。

• POST /v1/payments/authorization/<Authorization-Id>/capture
• POST /v1/payments/authorization/<Authorization-Id>/void
• POST /v1/payments/authorization/<Authorization-Id>/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 中，因为它们都是动词而不是名词？

或者在完整的apis url中使用这些词可以吗？

Answer 1

来自 REST API Design Rulebook 的一些片段关于不同的资源类型:

Document

A document resource is a singular concept that is akin to an object instance or database record.

Example: http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet

Collection

A collection resource is a server-managed directory of resources. Clients may propose new resources to be added to a collection. However, it is up to the collection to choose to create a new resource, or not.

Example: http://api.soccer.restapi.org/leagues/seattle/teams

Store

A store is a client-managed resource repository. A store resource lets an API client put resources in, get them back out, and decide when to delete them. On their own, stores do not create new resources; therefore a store never generates new URIs. Instead, each stored resource has a URI that was chosen by a client when it was initially put into the store.

Example: PUT /users/1234/favorites/alonso

Controller

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.

Like a traditional web application’s use of HTML forms, a REST API relies on controller resources to perform application-specific actions that cannot be logically mapped to one of the standard methods (create, retrieve, update, and delete, also known as CRUD).

Controller names typically appear as the last segment in a URI path, with no child resources to follow them in the hierarchy.

Example: POST /alerts/245743/resend

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

Rule: A verb or verb phrase should be used for controller names

Examples:

• 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

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

• Rule: A singular noun should be used for document names
• Rule: A plural noun should be used for collection names
• Rule: A plural noun should be used for store names