I'm working on a Rails app that needs to expose a RESTful web service. I'm curious to know some of the best practices as it relates to RESTful API design.
Let's say I have a set of related objects on the server side. I'll use the venerable subscribers, subscriptions and magazines example to lay it out.
class Subscriber < AR has_many :subscriptions has_many :magazines, :through => :subscriptions end
class Subscription < AR belongs_to :subscriber belongs_to :magazine end
class Magazine < AR has_many :subscriptions has_many :subscribers, :through => :subscriptions end
Does it make sense for this relationship to get exposed through the REST API? Put another way, does it make sense to support a GET operation where the URL looks like this? http://example.com/subscribers/3/subscriptions/19/magazines/12.xml
Or, should the API force smaller steps such that a web service client needs to do multiple GETs like: http://example.com/subscribers/3.xml # returns a list of subscriptions for subscriber.id == 3
http://example.com/subscriptions/19.xml # returns a list of magazines for subscriptions.id == 19 (already "constrained" by the previous call to subscribers)
http://example.com/magazines/12.xml # id == 12 came from the prior call to #subscriptions
I know the API is stateless so any "state" maintained between calls has to be represented in the URL, but it just seems wrong to me that the object relationships get exposed in the URL with the long, single call. It seems cleaner to force the web service client to break it into separate ones for each resource.
The API also needs to support POST and PUT operations on the same set of related objects.
Oh, and let's assume there is some (at minimum) Basic HTTP Authentication going on here which is picked up by the Rails app to restrict the possible domain of retrievable db records.