URIs in REST API endpoints according to Restful practices

Question

I am planning to have these endpoints for our REST APIs.

1. PUT /tenant/:tenantId/users/save/:username

2. POST /tenant/:tenantId/users/invite

3. GET /tenant/:tenantId/users/fetch

4. GET /tenant/:tenantId/users/fetch/:username

5. PATCH /tenant/:tenantId/users/activate/:username

6. POST /tenant/:tenantId/groups/save/

Verbs such as save/fetch/activate are from the consistency point of view. Are these RESTFul according to the REST principles? How should these be changed if at all? Any recommendations?

Answer 1

According to this REST Resource Naming Guide :

RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties which verbs do not have – similar to resources have attributes.

And also

URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is performed.

So let's take your first URI as example

PUT /tenant/:tenantId/users/save/:username

Here you are using the verb save . As mentioned before you should not be indicating a CRUD operation in the URI, in this case using a POST would be more appropriate. Here is a guide with the purpose of each HTTP verb. Knowing this, I think that for example a more appropriate URI for that case would be something like

POST /tenants/:tenantId/users/:username

In this cases:

GET /tenant/:tenantId/users/fetch

GET /tenant/:tenantId/users/fetch/:username

you should remove the fetch because you are already telling through the GET verb that data is being fetched. Same goes for the 6th example.

But, this doesn't mean that you can't use verbs in your URIs, in fact there is a specific category called controller which as mentioned in the same guide:

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs. Use “verb” to denote controller archetype.

This controllers resources could go well (I asume) with for example your

GET /tenant/:tenantId/users/activate/:username .

But I would think that the verb activate should go last:

GET /tenant/:tenantId/users/:username/activate

Answer 2

First note: REST doesn't care what spelling conventions you use for your resource identifiers. Once you figure out the right resources, you can choose any identifiers for them that you like (so long as those identifiers are consistent with the production rules defined in RFC 3986 ).

"Any information that can be named can be a resource" ( Fielding, 2000 ), but its probably most useful to think about resources as abstractions of documents. We use HTTP as an application protocol whose application domain is the transfer of documents over a network .

• GET

This is the method we use to retrieve a document

• PATCH
• PUT
• POST

These methods all indicate requests to edit a document (specifically, to edit the request target).

PUT and PATCH are each ask the server to make its copy of a document look like the client's local copy. Imagine loading a web page into an editor, making changes, and then "saving" those changes back to the server.

POST is less specific; "here's a document that we created by filling in a web form, edit yourself appropriately". It is okay to use POST : after all, the web was catastrophically successful and we're still using POST in our form submissions.

The useful work is a side effect of these edits.

---

Are these RESTFul according to the REST principles?

Do they work like a web site? If they work like a web site: meaning you follow links, and send information to the server by submitting forms, or editing the webpages and submitting your changes to the server, then it is REST.

A trick though: it is normal in REST that a single method + request uri might have different useful side effects. We can have several different HTML forms that all share the same Form.action. Uploading changes to an order document might have very different effects if the edits are to the shipping address vs to the billing information or the order items.

Normal doesn't mean obligatory - if you prefer a resource model where each form request goes to a specific resource, that can be OK too. You get simpler semantics, but you support more resources, which can make caching trickier.