We have a more or less "typical" ReST API that allows clients to interact with a bunch of resources, let's say Maps and Devices. An authenticated client can get a list of maps, it can download a map, upload a map and do similar things with devices.
Currently the resources have URIs that are modeled something like this:
- Retrieve all your maps:
- Retrieve a specific map:
- Upload a map (a multipart form upload):
All these requests are in the context of an authenticated client, that means that a client FOO can not see the maps of client BAR and if you GET the /maps collection, you obviously only see your maps.
Now we want to build an Admin-UI on top of this service. This means that a user with a certain role (an "Administrator") should be able to access all accounts and perform operations like delete accounts, create new ones, etc. This is no problem, we can just add a new resource called "accounts" and model that API.
However, the administrator must also be able to interact with the contents of any account he has access to. For example he needs to be able to see what maps an account FOO has and possible modify that collection.
We now have the problem that the original resource URIs are no longer sufficient to express this, since we need to somehow model the target account.
How do we design this? What makes the most sense? What are some common patterns?
Options we have discussed are:
- Have a second set of URIs that model the same resources as sub-resources of an account, e.g.:
/account/FOO/mapsinstead of /maps. This has the disadvantage of a having a lot of duplication and seems non-typical. It also does not allow operations over multiple account. This may not be a current requirement, but it seems reasonable to expect.
- Model the "target" account as some sort of orthogonal parameter (a Header? A Matrix Parameter? A URL parameter?) and assume that when this parameter is not present, the current client's account is to be used. This would allow current clients to continue to operate normally and the admin client can add this to the request. E.g.:
Are we missing anything obvious? How are other people doing this?