I'm stuck designing URIs for a many-to-many relationship between users and other resources. Specifically I'm having difficulty predicting the consequences of different approaches.

Given a resources types user and widget (user represents a registered user), authenticated (logged-in) users have write access to all widgets and guests have read access. The user-widget relation also has data (eg. number of edits) which ideally should also be readable (thus addressable) by guests (and, as Lèse points out below, other users). Examples use integers for unique identifiers for the sake of clarity.

Guests can view widget #12 at

/widgets/12

What are the implications of various possible URIs for authenticated user #34 to read/write widget #12, and optionally for a guest to read the relational data between the two? (Don't worry about giving a comprehensive answer, any observations for or against specific options would also be very valuable).

/widgets/12

(user is implicit based on authentication, no way for guest to specify user-widget relation)

/users/34/widgets/12

(both sides of the relation explicit, implicit hierarchy between resources)

/users/34/widgets/12 and /widgets/12/users/34

(same, without hierarchy)

/user-widget/34,12

(relation as resource, explicit but possibly more than the user needs to know)

I'm happy to give more detail or add other people's URI suggestions. Just comment if you want me to add anything.

3 Answers
3

The URL for accessing the widget should be the same for everyone. The control of what to show or what capabilities the user has is dependent on the userid, which could be kept, for example, in a session variable.

So when widget/12 loads, your web page should check who the user id is in the session variable, see what their permissions are, and then you would format the page based on those permissions.

I like "should be the same for everyone" - sounds like a good rule of thumb. Though as I state in the question this does not provide a location for guests to view user-widget relation data. What URI would you then suggest for that and why? Thanks!
–
Ian MackinnonSep 9 '10 at 12:33

The URI won't solve the IA issue of how and where you're displaying the user-widget relation data. Is the data on the widget page? Is the data on a separate data visualization page? You need to answer those questions first...which you may already have... If the user-widget data is on their own page then /user-widget/12 would show data for ALL users for that widget. If you want a specific user-widget page, /user-widget/12/34 would work. (use mod-rewrite and you can accept 12 and 34 as parameters in your script)
–
milesmeowSep 9 '10 at 15:17

How does the /widgets/12 form allow guests to read the widgets—or allow users to read the widgets of other users? Or are you planning on implementing multiple forms?

Personally, I would do something like:

/widget/id:12/user:665
/widget/12/665
/widget/12?user=665

Ultimately though, the URL doesn't matter unless this is going to be something that users are gonna want to access directly. If it's just a location to an embeddable script, data feed, or some other type of service, then you can use any URL you want, in which case I'd just go with something like:

/widget?id=12&uid=665

Edit:
I prefer to just serve the widget under /widget since that is what the resource is. I assume that the user-widget relationship is implied by the type of widget it is. So adding users into the path hierarchy is unnecessary.

Now, if you wanted people to be able to browse the widgets of a particular user, then the /users/34/widgets/12 form would be preferable.

Thanks for the point about users viewing other users' relations - an important point I hadn't considered. Will add this to the question.
–
Ian MackinnonSep 9 '10 at 12:24

Could you please give reasons why you would prefer URIs under /widget/ as opposed to under /users/ or revealing the user-relation resource directly? I'm most interested in whether there are advantages or tradeoffs in choosing particular designs. Thanks!
–
Ian MackinnonSep 9 '10 at 12:29

Also, on your second point I think it's best to assume that anything useful enough to be a resource is useful enough to be accessed directly by a human user.
–
Ian MackinnonSep 9 '10 at 12:30

@Ian Mackinnon: What I meant was, if it's a JSON service or some other web service that would not be intended for direct viewing regardless of how useful the data is.
–
Lèse majestéSep 9 '10 at 13:50

It's not about authentication. The user forming part of the relation can be implied to be the user who is currently securely authenticated. I'm not suggesting that authentication be provided by specifying a user identifier in the URI. Sorry if that was unclear.
–
Ian MackinnonSep 8 '10 at 19:41