Question

I’m a REST noob trying to design my first REST API schema.

Consider a simple REST API for listing/viewing/editing/deleting user objects. We could use the following 2 URL patterns for routing:

/users          # GET returns a list of users, POST allows creation of new user
/users/{userid} # GET returns user info, PUT for updating user info, DELETE to delete user

So far, so good. Now let’s say that users can be arranged in nestable folders. So a user could now be inside a folder, and a folder can contain both users and sub-folders. To allow management of folders, we want to add the following functions to our API:

• List contents (users and sub-folders) of a folder
• Create a new folder
• Rename, delete folders
• Move a user or sub-folder to a different parent folder

What is the best way of providing this functionality in a REST API? I came up with two ideas:

Idea 1: Show folder hierarchy in URL

e.g. /users/folder1/folder2/chris

At first glance this looks nice, but there are a number of problems with this approach:

• Both users and folders now have the same URL pattern. It’s impossible to know whether /users/a/b/c points to a user or a folder. This makes for a difficult to understand API, and an annoying implementation involving manual parsing of URLs and guesswork.

• When the client sends a POST to /users/folder1 we don’t know whether they want to create a new user or a new sub-folder. They will have to specify in the request body. Again this leads to an annoying server-side implementation, and does not seem very RESTful.

• No obvious way to allow moving of resources from one folder to another

Idea 2: Add parent folder info to resource

Keep the simple 2 URL patterns shown above, and add a parentFolder field to the user resource.

e.g. a GET to /users may return (in JSON):

{'users': 
   [{'name':'chris','DoB':'1/1/1900','parentFolder':'/folder1/folder2'},
   ...]
}

Add separate URL pattern /folders and /folders/{folderid} for viewing/editing/deleting folders.

This solves some of the problems with Idea 1, but in terms of design it makes me uneasy:

• Adding a resource’s parent as an attribute of the resource seems strange.

• Why do we have to separate users and their folders into separate APIs, even though they are so obviously inter-related?

Thanks for reading this far. Are they are any better ways of dealing with this?

Answer 1

There is definitely nothing strange about adding a link to your user resource to identify the containing folder. RESTful design is 95% about adding links between resources and 5% about deciding on what the URI looks like.

Doing a POST to /users/a/b/c with either a user resource or a folder resource should not cause you concern. One of the major advantages of doing RESTful HTTP is that you are not constrained by the limits of RPC. We are used to procedure calls that statically define what are the input parameters and the output parameters. HTTP has headers fields like Content-Type that allow input and output parameters to be defined at runtime.

I believe you are correct that option #2 will likely be easier to dispatch on the server than option #1. However, as long as you avoid URI construction on the client by using the server to return all the links the client might need, either option should be fine for your client.

Moving users around can be as simple as POSTing a user to a new folder and letting the server figure out if it needs to remove the user from the old folder.