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

Answer 2

The trick is to make it all nouns (or entities) that operate with the CRUD verbs.

So instead of;

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

Do this;

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

Answer 3

In REST, the verb is the HTTP method. In your example it is POST but it could also be GET, PUT, or DELETE.

The noun is the resource identified by the URL. In your example the "nouns" are /v1/payments/authorization/<Authorization-Id>/capture, etc.

As you can see, this is not really a noun since capture is a verb: capture a payment authorization. This is not RESTful since it is a command, a verb, not a thing, a noun.

A better way would be to model these commands as things like /v1/payments/authorization/<Authorization-Id>/capturecommand. This command would be a thing, a noun. It could have state, for example if it was successful, what was the result, etc.

There is a lot of code out there that claims to be RESTful and isn't.

Answer 4

Reviving an Old post, The ideology behind REST Api following a noun-based naming is that URLs are resource location, so they locate a resource. At times I would agree that it is difficult to represent things as resource. And a 95% or 90% design is still a good design. Problem comes when we would not give it a proper thought before accepting it cant be done.

For example, in the OP's scenario, the resource is authorization state. Values of states can be true/false or authorized/not authorized.

With this we have two resources now,

POST /v1/payments/authorization/<Authorization-Id>/ (authorize)
DELETE /v1/payments/authorization/<Authorization-Id>/ (void)

Now, when we come to reauthorize, technically it is void+authorize. But I would avoid doing this, if I had to do a round trip to achieve it.

Let us think of a scenario, what happens when we call authorize twice? Will I have two authorizations? Or it should be void and then authorize?

If it is former, I would probably follow an imperfect design, for its performance merits, and do,

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

But if it is the later, my only set of APIs will be,

PUT /v1/payments/authorization/<Authorization-Id>/ (authorize/reauthorize)
DELETE /v1/payments/authorization/<Authorization-Id>/ (void)

PUT verb here implies idempotency. So you can call it multiple times, and the effect is same.