RESTful POSTS, do you POST objects to the singular or plural Uri?

Question

Which one of these URIs would be more 'fit' for receiving POSTs (adding product(s))? Are there any best practices available or is it just personal preference?

/product/ (singular)

or

/products/ (plural)

Currently we use /products/?query=blah for searching and /product/{productId}/ for GETs PUTs & DELETEs of a single product.

Answer 1

Since POST is an "append" operation, it might be more Englishy to POST to /products, as you'd be appending a new product to the existing list of products.

As long as you've standardized on something within your API, I think that's good enough.

Since REST APIs should be hypertext-driven, the URI is relatively inconsequential anyway. Clients should be pulling URIs from returned documents and using those in subsequent requests; typically applications and people aren't going to need to guess or visually interpret URIs, since the application will be explicitly instructing clients what resources and URIs are available.

Answer 2

Typically you use POST to create a resource when you don't know the identifier of the resource in advance, and PUT when you do. So you'd POST to /products, or PUT to /products/{new-id}.

With both of these you'll return 201 Created, and with the POST additionally return a Location header containing the URL of the newly created resource (assuming it was successfully created).

Answer 3

You POST or GET a single thing: a single PRODUCT.

Sometimes you GET with no specific product (or with query criteria). But you still say it in the singular.

You rarely work plural forms of names. If you have a collection (a Catalog of products), it's one Catalog.

Answer 4

In RESTful design, there are a few patterns around creating new resources. The pattern that you choose largely depends on who is responsible for choosing the URL for the newly created resource.

If the client is responsible for choosing the URL, then the client should PUT to the URL for the resource. In contrast, if the server is responsible for the URL for the resource then the client should POST to a "factory" resource. Typically the factory resource is the parent resource of the resource being created and is usually a collection which is pluralized.

So, in your case I would recommend using /products

Answer 5

I would only post to the singular /product. It's just too easy to mix up the two URL-s and get confused or make mistakes.

Answer 6

As many said, you can probably choose any style you like as long as you are consistent, however I'd like to point out some arguments on both sides; I'm personally biased towards singular

In favor of plural resource names:

• simplicity of the URL scheme as you know the resource name is always at plural
• many consider this convention similar to how databases tables are addressed and consider this an advantage
• seems to be more widely adopted

In favor of singular resource names (this doesn't exclude plurals when working on multiple resources)

• the URL scheme is more complex but you gain more expressivity
• you always know when you are dealing with one or more resources based on the resource name, as opposed to check whether the resource has a id looking path parameter following
• plural is sometimes harder for non-native speakers (when is not simply an "s")
• the URL is longer
• the "s" seems to be a redundant from a programmers' standpoint
• is just awkward to consider the path parameter as a sub-resource of the collection as opposed to consider it for what it is: simply an ID of the resource it identifies

Answer 7

you could use the same url for all of them and use the MessageContext to determine what type of action the caller of the web service wanted to perform. No language was specified but in Java you can do something like this.

WebServiceContext ws_ctx;
MessageContext ctx = ws_ctx.getMessageContext();
String action = (String)ctx.get(MessageContext.HTTP_REQUEST_METHOD);
if(action.equals("GET")
  // do something
else if(action.equals("POST")
  // do something

That way you can check the type of request that was sent to the web service and perform the appropriate action based upon the request method.