What is the best way to design REST URI for nested resources

Question

Say there are users having multiple authorizations having multiple permissions.

Retrieving all authorizations for the specified user (without permissions) could be:

GET users/{id}/authorizations

The "normal" case is to not embed permissions with authorizations for performance reason.

There are cases when authorizations must be returned with their respective permissions for that user.

Suggested solutions are:

GET users/{id}/authorizations/permissions       // does not seem clear
GET users/{id}/authorizations?permissions=true  // with query string
GET users/{id}/authorizationswithpermissions    // new resource

Now what is the best way to design the REST URI in that case?

Answer 1

Your ideas

There are cases when authorizations must be returned with their respective permissions for that user.

GET users/{id}/authorizations/permissions

It is not a good idea to nest collection resource like this. Does it mean "give me all permissions of all authorizations of user id"? This is unclear. Don't do this.

GET users/{id}/authorizations?permissions=true

A query is normally used to query, search, or filter on a collection resource. This URL woud return all authorizations for user id for which permissions is true. But what does that man? This is unclear. Don't do this.

GET users/{id}/authorizationswithpermissions

Authorizations are authorizations. Their representation should not depend on the URI. Don't do this.

Content Negotiation

The solution to your problem is to use content negotiation. You only use one URL:

GET users/{id}/authorizations

This means: Give me a list of all authorizations of user id.

Now if you want to get this list without permissions, you could use the HTTP header

Accepts: application/vnd.mycompany.authorizations+xml

Let's digest this.

• application: the first part of the normal MIME type application/xml
• vnd: a prefix to define your own type
• mycompany.authorizations: your type
• xml: the second part of application/xml

Now if you want to get this list with permissions, you could use the HTTP header

Accepts: application/vnd.mycompany.authorizations.permissions+xml

Note that me now use vnd.mycompany.authorizations.permissions. The server should return the authorizatons including the permissions. Only the representations are different, not the resources.

Answer 2

Personnally I can't find any problem with both two last suggestions:

GET users/{id}/authorizations?permissions=true  // with query string
GET users/{id}/authorizationswithpermissions    // new resource

Except I would change them as follow to be more relevant:

GET users/{id}/authorizations?withPermissions=true  // with query string
GET users/{id}/authorizationsANDpermissions    // new resource

The first one seems to be quite confusing but your RESTful entities should be documented whatever notation you will opt for.