Menu
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?
469
Simply because RESTful APIs are based on resources and use the HTTP verbs (GET, POST, PUT, DELETE, PATCH), does not mean they should only support CRUD (Create, Read, Update, Delete) operations. RESTful APIs can also be used for performing other actions on resources.
The answer does not usually change: it depends. In the case of less complex cases, where we are applying the concepts of REST to a CRUD, there will rarely be times when we need an endpoint that contains a verb.
Plural Nouns Are Preferable, Rather Than Singular Using plural or singular nouns for defining resources has no any impact on how your API will work; however, there are common conventions that are used in all good RESTful APIs. One of such conventions is the use of plural nouns for defining resources.
HTTP verbs are preferred if possible, as they are part of the HTTP protocol and as such a standard. It also allows you to use existing security and caching layers on a standard web server, without having to write any bespoke middleware.
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.
Since the URL or URI refers to a resource, it is natural to point that to a noun instead of verb. However, there are conflicting suggestion in the industry when it comes to this. Another point is in RESTful APIs major operations such as POST,GET, PUT, DELETE forms a CRUD ( Create, Read, Update and Delete) Use Case.
Our HTTP verbs are POST , GET , PUT, and DELETE. (I think of them as mapping to the old metaphor of CRUD ( C reate- R ead- U pdate- D elete).) With our two resources ( /dogs and /dogs/1234) and the four HTTP verbs, we have a rich set of capability that's intuitive to the developer. Here is a chart that shows what I mean for our dogs.
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.
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/trebuchetCollection
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/teamsStore
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/alonsoController
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/registerhttp://api.example.restapi.org/lists/4324/dedupehttp://api.ognom.restapi.org/dbs/reindexhttp://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
131
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. If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
