Confusion Between Noun vs. Verb in Rest URLs

43
votes

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?

3
restrestful-url

3 Answers

38
votes

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
11
votes

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.
10
votes

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.