Naming Rest URLs [closed]

What would be a good practice if I need to deliver the following:

First

I was thinking of /page/{id} ( for json info ) and /page/{id}/download for doc format ( is there a recommendation for this ? )

Second

Should I build a new resource like /bookstatus or should I provide multiple options for the main resources /book/{id}/status and /book/{id} for all information

All I need to know if there are some best practice and naming conventions for the url in cases like this !

[Academic rant] REST does not recommend URI templates since the client would need to know this out of band information. You can add some of you like but make it easy to guess or code. [/Academic rant]

The approach is to get an entry point to your application and then use links to guide your client. Like this your application interface is discovered and out of band info is kept to a minimum.

The type of representation that you serve is done via content negotiation or explicitly request by your client. For example some ideas:

GET /mybooks (Content negotiation or server decides - feel like html?)
GET /mybooks.xml 
GET /mybooks.json
GET /mybooks.csv
GET /mybooks.xhtml
GET /mybooks/{id}.doc (Download)
PUT /mybooks/{id} (Add a book / id to my list)
DELETE /mybooks/{id} (Remove from my list)
POST /mybooks (Add a book / id to my list)

Note: PUT is idempotent and POST not.

The list of books will be encoded in this media type, say descritpion with a link to the particular book. You can encode links in your hypermedia (JSON or xHtml) the way you want, but its better to use some standard (like the <link> and <a> tags) to reach a wider audience. You can then have named / types links to the formats that you want. For example some ideas:

GET /book/{id}.html (Status and other info)
GET /book/{id}/summary (Status and other info)
GET /book/{id}.doc (Download)
GET /book/{id}.zip (Download)
GET /book/{id}/chapter/{id}.doc 
POST /book (add book to database)
DELETE /book/{id} (Burn the book)

You can design the URIs as you want. But it makes it better if the resources can be discovered via links. You can use other verbs to such as OPTIONS, HEAD, GETBOOKINFO etc. but better stick to the standard ones.

As far as I know the naming convention is up to you (with something logic obviously). You will probabily use different verbs for the same resource/url.

/book/{id} with PUT, GET, DELETE /book with POST

It’s a best practice to make the URIs unique (means no redundancy in terms of the functionality) regardless of the type of content you deliver. Consider unification of URIs and deliver different content using content negotiation and HTTP accept headers.

So ideally, GET /book/{id} would deliver book details in the form of text/html, application/json, etc depending on the accept headers specified by the client.

http://www.w3.org/QA/2006/02/content_negotiation.html http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html

As Irido said, naming is totally up tu you. If I were in your shoes, I'd use parameter to determine the format of return data, eg. format=json or format=doc or something. If no format parameter specified, return default format. This way you don't have to do some fancy url manipulation if you want different format (just add another parameter into url). And you can easily add new formats, without need to re-think urls.