[Catalyst] Re: Actions for asserting relationships

[Aristotle Pagaltzis]

* Bill Moseley <moseley at hank.org> [2011-05-31 06:55]:
> I'm looking for more guidance wrt URLs.

Sorry for the late reply. I haven’t caught up with all my mail
in a very long time. But I thought an answer to this would be
of interest even if it comes after the fact.

> Say in the music database example that tracks have
> a many-to-many relationship to albums.  A track can be
> associated with zero or more albums.
>
> In the API for this we can POST, GET, PUT, and DELETE /track
> and /album. But, what about asserting relationships between the
> two?
>
> POST /album/$album_id/add_track { track  => $track_id };
> POST /album_track { album => $album_id, track => $track_id );
> POST /album/$album_id/track/$track_id  (or
> /track/$track_id/album/$album_id).
>
> The last one seems best as it allows associating other data
> with the relationship, and make DELETE make sense.

If you look at it as one aspect of an album being a collection
of tracks, then you want albums to have a collection sub-resource
for their list of tracks. Naturally you instantiate new members
in a collection by POSTing to the collection.

So something close to your option #1 falls out naturally – just
call the action `track` (a resource, here a collection) rather
than `add_track` (an action). (I’m not religious about not using
verbs when they’re more concise. But here it makes sense to me.)

And POSTing would result in a new /album/$album_id/track/$track_id
resource which can be DELETEd (and maybe PUTting, eg. changing its
position).

GETting /album/$album_id/track should of course return a list of
links to all the connection resources, as any collection would.

> And what HTTP status code should be returned if a) the
> relationship is created? b) the relationship already exists?
> I'm not sure it's important that there's a distinction if only
> need to assert that the relationship exists. But, a 201 really
> implies that the resource was created.

If you follow the above model this answers itself. You send 201
if the relationship is new and 303 if it’s not.

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>