api - Conventions for adding child objects via API (JSON) - Thin URL/Fat Body, or vice-versa?

Question

Say you have an api method that POSTS shelves to a wall:

POST /api/shelve  {wallId: 0, shelveTitle: "a shelve for my favorite books"}

And then you have another method that POSTS a book to a shelve:

POST /api/book {shelveId: 0, bookTitle: "my book"}

In terms of syntax and usability, would you rather have the above (thin URL, fat body), or a more verbose URL like this:

POST /api/shelve/0/book {bookTitle: "my book"}

I'm tempted to just keep the URL as simple as possible by saying /api/book and delegate all specification / definition to the body, restricting the URL to verb/noun pairs. I'm brand new to APIs and want to make sure I get off on the right foot... what's the convention in this scenario?

Answer 1

Personally I would go with

POST /api/shelve/0/book {bookTitle: "my book"}

because it's clear that you are adding a book to a shelve, rather then just adding a book.

Opinions vary on REST design, but I can really recommend this small, free book: Web Api Design