Correct Rest API endpoint

Question

Hi Im working on a REST API for a e-commerce app and had a couple questions about which are the correct URNs to map some specific actions, having in mind the definition of URI stated on RFC 3986: A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.

1. The action of sharing a post which receives an email and shares the post url via mail. Specific posts are mapped to /api/posts/id which is correct. The thing is I don't know how to map the URL of this action. A post to an URI like /api/posts/id/share is totally incorrect by definition of URI considering that share is an action and not a resource.
2. The action of resetting your password and the action of asking for a password reset email. Users are mapped to /api/users. Something like /api/users/password-reset-email and /api/users/password-reset would be incorrect following the same guideline explained before.

Answer 1

The key takeaway from the dissertation that introduced REST is:

Any information that can be named can be a resource...

Have a look at Resources and Resource Identifiers for more information.

In other words, an action is a resource. In your own words, a URI is a sequence of characters that identifies an "abstract or physical resource". Just because an action doesn't easily map to a tangible object doesn't make it less of a resource.

There are status codes which only exist to respond to 'actions' (e.g. 202 Accepted).

All in all, POST /api/posts/{id}/share seems completely reasonable.

POST is really there as a 'catch all' for actions. In RFC2616 it says the "function performed by the POST method is determined by the server" and the function performed "might not result in a resource that can be identified by a URI".

The main points:

1. An 'action' should almost always involve POST
2. The 'action' performed should relate to the URI and body of the POST request.
3. You should return an appropriate status code (e.g. 200, 201, 202, 204, 4xx).