# RESTful web service design question **URL:** \ **Category:** Rails\ **Created:** [November 22, 2006, 5:19pm UTC](https://www.ruby-forum.com/t/restful-web-service-design-question/76940 "2006-11-22T17:19:03Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![cremes](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/e19b73/32.png) [@cremes](https://www.ruby-forum.com/u/cremes)\ **Post date:** [November 22, 2006, 5:19pm UTC](https://www.ruby-forum.com/t/restful-web-service-design-question/76940/1 "2006-11-22T17:19:03Z")
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](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](http://example.com/subscribers/3.xml) # returns a list of subscriptions for subscriber.id == 3 [http://example.com/subscriptions/19.xml](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](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 ---
**Author:** ![cremes](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/e19b73/32.png) [@cremes](https://www.ruby-forum.com/u/cremes)\ **Post date:** [November 22, 2006, 5:33pm UTC](https://www.ruby-forum.com/t/restful-web-service-design-question/76940/2 "2006-11-22T17:33:05Z")
> 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](http://example.com/subscribers/3.xml) # returns a list of subscriptions for subscriber.id == 3 > > [http://example.com/subscriptions/19.xml](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](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](http://example.com/subscribers/3.xml) might return something like this: bob And so on. Steve ---
**Author:** ![cremes](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/e19b73/32.png) [@cremes](https://www.ruby-forum.com/u/cremes)\ **Post date:** [November 22, 2006, 7:13pm UTC](https://www.ruby-forum.com/t/restful-web-service-design-question/76940/3 "2006-11-22T19:13:28Z")
On Wednesday, November 22, 2006, at 10:55AM, “Bosko M.” [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > > > > nesting in the URI for GETs, so these would be acceptable: > DELETE /subscriptions/32 > 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 ---
**Author:** ![cremes](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/c/e19b73/32.png) [@cremes](https://www.ruby-forum.com/u/cremes)\ **Post date:** [November 22, 2006, 5:57pm UTC](https://www.ruby-forum.com/t/restful-web-service-design-question/76940/4 "2006-11-22T17:57:09Z")
On 11/22/06, removed\_email\_address@domain.invalid [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote: > class Subscription \< AR > [http://example.com/subscribers/3/subscriptions/19/magazines/12.xml](http://example.com/subscribers/3/subscriptions/19/magazines/12.xml) > The API also needs to support POST and PUT operations on the same set of related objects. > 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. – Bosko M. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) [http://www.crowdedweb.com/](http://www.crowdedweb.com/)