REST url proper format

Question

my REST API format:

http://example.com/api/v1.0/products - get all products
http://example.com/api/v1.0/products/3 - get product with id=3

Also, the products can be orginized into a product groups.

What is a proper way to get all product groups according to REST best practices:

http://example.com/api/v1.0/products/groups

or

http://example.com/api/v1.0/productgroups

...

another option ?

Answer 1

I can't agree with Rishabh Soni because http://example.com/api/v1.0/products/groups may lead to ambiguity.

I would put my money on http://example.com/api/v1.0/productgroups or even better http://example.com/api/v1.0/product_groups (better readability).

I've had similar discussion here: Updating RESTful resources against aggregate roots only

Question: About the thing of /products/features or /product-features, is there any consensus on this? Do you know any good source to ensure that it's not just a matter of taste?

Answer: I think this is misleading. I would expect to get all features in all products rather than get all possible features. But, to be honest, it’s hard to find any source talking directly about this problem, but there is a bunch of articles where people don’t try to create nested resources like /products/features, but do this separately.

So, we can't be sure http://example.com/api/v1.0/products/groups will return all possible groups or just all groups that are connected with all existing products (what about a group that has not been connected with the product yet?).

To avoid this ambiguity, you can add some annotation in documentation. But you can just prepare http://example.com/api/v1.0/product_groups and all is clear.

Answer 2

If you are developing Rest API for your clients than you should not rely on id's. Instead build a meaningful abbreviation and map them to actual id on server side.

If that is not possible, instead of using http://example.com/api/v1.0/products/3 you can use http://example.com/api/v1.0/products?product_id=3 and then you can provide "product_id" description in the documentation. basically telling the client ways to use product_id. In short a url must be meaningful and follow a pattern.The variable part must be send by in the url query(part after ? or POST payload)

With this, method to querying the server is also important. If client is trying to get something to the server he should use "GET" http request, similar POST http request if it is uploading new info and "PUT" request if it is updating or creating a new resource.

So by this analogy http://example.com/api/v1.0/products/groups is more appropriate as it is following a pattern(groups in product) while productgroups is more like a keyword with no pattern.

A directory like pattern is more easier to understand. Like in file systems(C:\Program Files\WinRAR), every part gets us to more generalized target.

You can also customize this for specific group- http://example.com/api/v1.0/products/groups?id=3