Resource and Action URI convention for REST
I am at a cross roads for developing some REST APIs and I have found no real discussion on the subject much less a firm defense of either.
It's my understand that with REST you have
/<resource>/<action> as your URL
So, to disable a user you would have:
Seems reasonable. However, we have the debate going on out more basic methods:
should it be:
POST /user (creates a user *implicitly*) POST /user/create (creates a user *explicitly*) DELETE /user/:id DELETE /user/:id/delete
The first seems to be what is considered "the standard" and the second is obviously much more clear in it's intent and is consistent with methods like /user/disable
Maybe this debate has raged elsewhere but I have not seen it. If you're 'religious' about this, now's your chance to pontificate
Resource and Action URI convention for REST, Having /<resource>/<action> as your URL is not REST. REST uses HTTP verbs to determine actions to perform on a given resource, or on a REST Resource Naming Best Practices Use nouns to represent resources. 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. Some examples of a resource are: Users of the system; User Accounts; Network Devices etc.
RESTful Resource Naming, Naming Tutorial: RESTful services are resource-based. URIs and HTTP verbs, and using them in line with the standards and conventions. In deciding what resources are within your system, name them as nouns as opposed to verbs or actions. In other words, a RESTful URI should refer to a resource that is a thing instead The service root URI identifies the root of an OData service. The resource identified by this URI MUST be an AtomPub Service Document (as specified in [RFC5023]) and follow the OData conventions for AtomPub Service Documents (or an alternate representation of an Atom Service Document if a different format is requested). OData: JSON Format
Having action in your URL is not REST.
My approach to solve this is to define an action sub-resource.
And you can do something like:
and request body as json:
Represent actions(verbs) in REST URI, POST doesn't mean "create", it means "process". You can create a new resource by posting a suitable request to an existing resource (i.e. post to /customers to In deciding what resources are within your system, name them as nouns as opposed to verbs or actions. In other words, a RESTful URI should refer to a resource that is a thing instead of referring to an action. Nouns have properties as verbs do not, just another distinguishing factor. Some example resources are: Users of the system.
10+ Best Practices for Naming API Endpoints, RESTful Resource Naming Conventions URIs as resources as nouns “RESTful URIs should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties which verbs do 2. REST Resource Naming . 2.1 Use Nouns for Naming. For RESTful URI, Nouns are better than verbs (verbs are discouraged).As a rule of thumb, your URI should refer to a thing (a noun) and not an action (verb).The reason for using noun is your API is its ability to represent properties. some examples. User; User Account; User’s Order; Products
Best practices for RESTful web services : Naming conventions and , Verbs refer to actions, which are used to factor HTTP actions. Three words that describe good resource naming conventions are as follows: For the DELETE operation, the HTTP request to the URI will be as follows: DELETE What are naming conventions. One of the keys to achieving a good RESTful design is naming the HTTP verbs appropriately. It is really important to create understandable resources that allow people to easily discover and use your services. A good resource name implies that the resource is intuitive and clear to use.
Methods, Methods can be executed on resources via their URL. As a solution to such non-RESTful operations, an “actions” sub-collection can be used on a resource. Before going over the rules for REST API URI design, let’s do a quick overview on some of the terms we are going to talk about. URIs. REST APIs use Uniform Resource Identifiers (URIs) to address resources. On today’s web, URI designs range from masterpieces that clearly communicate the API’s resource model like: