Rest URLs 中名词与动词的混淆 [英] Confusion Between Noun vs. Verb in Rest URLs

问题描述

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

I have studied over the internet about restful APIs that it focuses on nouns not verbs in the url pattern, but now I am seeing multiple links that use verbs in the URL.

这是一个例子.

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

这是 Paypal api.PayPal API

this is Paypal apis. PayPal API

也在维基百科的 HTATEOAS 页面上给出了一个例子；

also on wikipedia on HTATEOAS page they gave a example ;

<?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 中，因为它们都是动词而不是名词?

Can anyone help me get some clarity about this? why 'capture', 'void', 'deposit', 'withdraw', 'close' are in the URI cause they are all verbs not nouns?

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

or is this okay to use these kind of words in rest-full apis url?

推荐答案

REST API 的一些片段关于不同资源类型的设计规则手册:

文档

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

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

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

收藏

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

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.

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

商店

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

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.

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

控制器

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

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

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

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).

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

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

示例:POST/alerts/245743/resend

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

Based on the definitions in the book, the URIs you've posted probably fall under the Controller resource type, of which the book later states:

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

示例:

• 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

<小时>

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

---

Other naming rules, just for completeness

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

这篇关于Rest URLs 中名词与动词的混淆的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！