Why below request path is more restful?

Question

I have studied Play framework with 'Play for Java' book by manning.

This book introduces second request path is more restful than the first one. Because list of the page would be changed over time.

Even it could be changed, why second one is better?

GET /products/:page controllers.Products.list(page: Int)

GET /products/ controllers.Products.list(page: Int)

Answer 1

It's described actually in the book, first route requires the param, so even if you don't want to use any you need to...

/products/0
/products/1
/products/2

etc.

In second route param is optional, so it's useful when used with i.e. pager

/products
/products?page=1
/products?page=2

Of course you can create 2 routes with first approach to get the equivalent of optional param:

GET /products         controllers.Application.products(page: Int ?= 0)
GET /products/:page   controllers.Application.products(page: Int)

First is nicer, when you passing always the same amount of params AND all of them are required

GET /cars/:manufacturer/:model/:option  controllers.Application.cars(manufacturer, model, option)
Which must be: /cars/BMW/Z4/Pure-Balance

On the other hand second route is more comfortable when you have a large amount of optional params in it

GET /filter  controllers.Application.filter(query, order, direction)
which can be:
/filter?query=something&order=name&direction=desc
/filter?order=branch
/filter?query=something-else

etc.

We can't say that one is better, second is worse, just both has other usage, take a look to the docs to get familiar with optional params, fixed values and default values

Answer 2

The url path should always be a unique resource identifier.

The page is far from an unique identifier. It is part of the current request as a mapreduce param, so you should send it in range headers or in the queryString.

For example:

• GET /products?page=1&count=1 - always returns a representation of a collection resource containing the first item resource depending on the sorting
• GET /products/1 - always returns the representation of the same item resource which has id=1

Btw I recommend you to read about DDD and bounded contexts, "product" is probably not the best word, at list not in this format...