Question

Is this a good structure for REST URLs?

Assuming:

GET /account  <- get list of accounts
GET /account/1234 <- get account 1234

etc.

If the account resource has a collection that I want to interface, is this a good idea?

GET /account/1234/note <- get notes for account 1234
POST /account/1234/note <- add note to account 1234
DELETE /account/1234/note/321 <- delete note 321 on account 1234

Especially that last one gives me pause; typically I wouldn’t require both the entity ID and the parent ID when deleting.

Or maybe something like this would be better?

GET /account-note/1234 <- get notes for account 1234
POST /account-note/1234 <- add note to account 1234
DELETE /account-note/321 <- delete note 321 on account 1234 (b/c note 321 is on account 1234)

But then I’d end up with a pretty shallow URL set.

Thanks

Answer 1

I referenced this question in my comments on another question and between the feedback I got there and my own research this is what I’ve come up with.

Firstly, the question is sort of flawed. RESTful APIs, or to use the perferable term Hypermedia APIs should include the urls of related actions so that the interface is discoverable and changes won’t break existing clients, therefore the exact structure has significantly less importance than I was placing on it, these can be changed later.

Secondly, the note in the example will be retrieved as part of an account query, maybe something like this:

<account>
   ...
   <notes>
      <note>
         ...
         <link href="/account-note/123" rel="note">
      </note>
   </notes>
</account>

The client will never be assembling urls to the account on their own, the client will use the link provided. Since the note ID is globally unique in this case, there is no need to include the key twice. Hence the answer to the question is no, the first example is not a good REST url structure, the second one is better. (Although still maybe not the best…)