I often get into issue like this, very similar to this Hierarchical RESTful URL design
Supposed the service only offers the user to upload a document.
POST, GET /accounts
PUT, DELETE /accounts/{name} or /accounts/{id}
Now a document is attached to a specific user, whether it is public or not at all is not of concerned here.
The two ways are POST /documents vs POST /users/documents
Why? Because later when a document resource is created, that document is under the user's control. So I would expect to have
GET, PUT, DELETE /users/{name}/documents
for getting, changing and deleting a bunk of documents the users own.
I can have GET, PUT, DELETE /users/{name}/documents/{name/id}
But the same can be achieved just /documents/{users}/.... or /documents/{id}
. And this is similar to how one might organize unix files (though /users/...
is also another way to organize files...) You see, there is also a philosophy[phy of uri vs url design.
Another consideration is whether the API is visible to user or not. If this is simply a backend API, only the developer has access (backend <- frontend server <- frontend ajax)
, then a site user may be happier with /users/{name}/documents/{id/name}
while some programmers will dislike this long url if the API is public (like twitter api).
What do people think about these issues?