RESTful web service design question

rubyonrails-talk
1

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

2

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.

I'm a REST newbie as well. I'm looking forward to seeing other's responses to this question. However I don't see anything inherently un-RESTful about your second approch, as long as the first request returns machine navigatable links to the sub-items. That way it's still stateless. For example,

  http://example.com/subscribers/3.xml

might return something like this:

  <subscriber id="3">       <name>bob</name>       <subscriptions>         <subscription id="14" xlink:href="http://www.magazines.com/subscriptions/14&quot;/&gt;         <subscription id="19" xlink:href="http://www.magazines.com/subscriptions/19&quot;/&gt;       </subscriptions>   </subscriber>

And so on.

Steve

3

The way I would do this is not go beyond the 2nd level of resource nesting in the URI for GETs, so these would be acceptable:

GET /subscribers/12 GET /magazines/2 GET /subscribers/12/subscriptions GET /magazines/2/subscriptions

POST, PUT, and DELETE subscriptions as follows, though:

POST /subscriptions/32 PUT /subscriptions/32 DELETE /subscriptions/32

There is no 'state' carried across in these examples, by the way. For instance, nothing should prevent someone from doing a GET on Joe's subscription to "Blah", without first doing a GET on Joe, so GET /subscriptions/32 should also be legal.

4

Okay, that looks all right. I certainly like it a lot better than stringing them all out which would require a pretty complex nested resource map in routes.rb. It would suck trying to debug one nested 3 or 4 deep.

Thanks for your response. Now I know I'm not too far off from reality with my design.

cr