Confusion Between Noun vs. Verb in Rest URLs

Question

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.

Here is an example.

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

this is Paypal apis. PayPal API

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>

link: Wiki HATEOAS

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?

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

Answer 1

Some snippets from the REST API Design Rulebook about different resource types:

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

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:

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

---

Other naming rules, just for completeness

• 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