RESTFUL formatting of URLs

Question

Simple question, in terms of best practice is it better to format my URL like this:

http://www.example.com/search?query=hello&page=1

or like this:

http://www.example.com/search/hello/page/1

Can you provide a valid reason for your choice please.

Answer 1

First one fits the situation where you want to "filter" your result if it gets a little too complicated, like this example:

cars.com/audi/sedan/a/4/black/manual.....

this is gonna take so long and complicated and result will be nightmare, but this would work better:

cars.com/mercedes/amg?color=white&transmission=manual

2nd way is just like thinking it of a 'folder'ed structure:

socialmedia.com/shares/1/comments/1/page/2

I am pretty sure you get the idea.

p.s. if you will provide your API to a brand new clients, who don't know anything about it, then first one is also more understandable but, i suggest you also have a API documentation which describes the parameters and the relevant poasible other calls as well. in this way your url formatting will be clearer and clients will not struggle to solve parameters in the url.

Answer 2

The first way is not only functional, but lets a human understand what the name/value pairs are. Sure you could go into configuration and string manipulation and make your URL look like the second example and still function, but from a readability pov and ease of function, the first one is best.