How to model an Admin View on a ReST API

Question

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: GET /maps
• Retrieve a specific map: GET /maps/1234
• Upload a map (a multipart form upload): POST /maps
• etc

Very straightforward.

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:

1. Have a second set of URIs that model the same resources as sub-resources of an account, e.g.: /account/FOO/maps instead 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.
2. 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.: GET /maps;account=FOO

Are we missing anything obvious? How are other people doing this?

• AilurusFulgens: So basically the resource representation of a particular account is a kind of collections containing every Maps managed by this particular account ?
• guillaume31: Why didn't you choose option 1 for all URIs in the first place? It isn't duplication, it's multi-tenant management. uberjack.com/2013/08/client-ids-in-multitenant-restful-api-uris
• Boris Terzic: Well, first of all we didn't have the admin requirement for many years, so that is simply an evolution of the product. Furthermore this is fundamentally the case for any ReST API where many clients can have their own view on the world, which is a large subset of existing ReST APIs. As far as I have seen, modeling the account as a super-resource is seldomly done and I was wondering if there are any existing best practices, or approaches that we are missing. BTW thanks for the link! That is indeed thinking along exactly the same lines.