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?

score 37 · Answer 1 · answered Nov 25 '14 at 08:51

37

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

answered Nov 25 '14 at 08:51

Paul Samsotha

188,774
31
430
651

8

The authors of this book may have the opinion, that RPC is fine. They may even call RPC "controller resource". But I disagree that this is good advice since there is no resource at such a URI that can be acted on using the other HTTP verbs. `GET /.../reindex` makes no sense which is a strong indicator that the whole URL makes no sens. – Nov 25 '14 at 09:29
1

@LutzHorn The book did not imply that `GET /../reindex` should be used. I don't want to quote the everything, but the implication was to use POST. GET should be used for a CRUD retrieve operation, which the book clearly states should not be defined by a controller – Paul Samsotha Nov 25 '14 at 09:34
3

So such a controller is not a resource in the REST sense. I vote against this concept. – Nov 25 '14 at 09:35
@LutzHorn Just curious on your opinion.. How would _you_ define an operation in REST terms, that is not a CRUD operation? Also are you saying that "action" operations have no place in REST. Just would like to hear different views – Paul Samsotha Nov 25 '14 at 09:41
An operation is a resource that is created by `POST`ing to a collection of operations. `POST /.../item/1/ops` with details in the body. The response contains the `Location` header of the resource. A `GET` retrieves the current state of the resource. Summary: an operation is just like any resource. – Nov 25 '14 at 09:44
2

@LutzHorn But what you are describing is CRUD (create) operation. I am asking about operations that _"can't logically be mapped to CRUD"_. The example URI above for controller says _"..resource that allows a client to resend an alert to a user"_. What are your thoughts on this? – Paul Samsotha Nov 25 '14 at 10:06
Every operation *can* be logically mapped to CRUD. Even the resend request can. – Nov 25 '14 at 10:07
6

It sounds like some of the commenters are rejecting the notion of a "Controller" resource type as part of a REST API, because it does not fit within the CRUD model. But is that saying that only CRUD APIs are "good" and anything that goes beyond CRUD is "bad"? I understand the problems that occur with an unconstrained RPC model, but I'm not sure I accept that the CRUD model is the answer for every problem. More elaboration on when it's OK to use the "controller resource" would be useful. – Duncan Oct 12 '17 at 23:15

nesty · Answer 2 · 2021-05-06T02:57:18.967

11

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.

edited May 06 '21 at 02:57

answered Aug 15 '16 at 13:32

nesty

429
5
6

Upvote not because it's "RESTful" this way but far more elegant. – Tech Nomad Nov 21 '19 at 07:24

score 9 · Answer 3 · answered Nov 25 '14 at 08:39

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.

I especially like the final statement: `> There is a lot of code out there that claims to be RESTful and isn't.` — Ivaylo Slavov, Nov 25 '14 at 08:43
I have to disagree. When you start namifying verbs for no reasons, that's a good sign you might want to take a break, breath, and remind yourself that those rules are made for your code, not the other way around. — lapin, Apr 18 '19 at 15:06

Confusion Between Noun vs. Verb in Rest URLs

3 Answers3

Linked