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.
Thoughts?
cr