{
"attachments": [],
"comments_archived": true,
"date": "2004-09-15T18:48:53.000Z",
"excerpt": "So... am I missing a more elegant RESTful way of doing this which doesn't result in a quadrillion HTTP requests?",
"layout": "post",
"tags": [
"xml"
],
"title": "Manipulating aggregate resources in a REST API?",
"wordpress_id": 547,
"wordpress_slug": "manipulating-aggregate-resources-in-a-rest-api",
"wordpress_url": "http://www.decafbad.com/blog/?p=547",
"year": "2004",
"month": "09",
"day": "15",
"isDir": false,
"slug": "manipulating-aggregate-resources-in-a-rest-api",
"type": "entry",
"postName": "2004-09-15-manipulating-aggregate-resources-in-a-rest-api",
"html": "Here's a tiny bit of a REST-ian quandary: I'm working through this API for dbagg3. The major resources involved include subscriptions and entries. Quite often, while working on the UI, I find a need to manipulate ranges and collections of these resources-- things like: “mark these 12 entries as read” and “give me an aggregate of the new entries for these 6 subscriptions”.
\nSo, I have been using URLs like the following:
\n\nPOST /subscriptions/523/entries/12322,12326,12325,12388,12412/notes/GET /subscriptions/312,443,523/now-12.xml
\nDoing things this way is terribly convenient with regard to stuffing many things into one HTTP request. Problem is, with respect to REST, these URLs no longer refer to individual resources-- they're aggregate references.
\nI've been thinking about this apparent break with the REST philosophy, and was reminded of it after skimming through Mark Baker's notes on a talk today.
\nSo... am I missing a more elegant RESTful way of doing this which doesn't result in a quadrillion HTTP requests?
\n\n\n\n",
"body": "Here's a tiny bit of a REST-ian quandary: I'm working through this API for `dbagg3`. The major resources involved include **subscriptions** and **entries**. Quite often, while working on the UI, I find a need to manipulate ranges and collections of these resources-- things like: “mark these 12 entries as read” and “give me an aggregate of the new entries for these 6 subscriptions”.\r\n\r\nSo, I have been using URLs like the following:\r\n\r\n* `POST /subscriptions/523/entries/12322,12326,12325,12388,12412/notes/`\r\n* `GET /subscriptions/312,443,523/now-12.xml`\r\n\r\nDoing things this way is terribly convenient with regard to stuffing many things into one HTTP request. Problem is, with respect to REST, these URLs no longer refer to individual resources-- they're aggregate references.\r\n\r\nI've been thinking about this apparent break with the REST philosophy, and was reminded of it after skimming through [Mark Baker's notes on a talk][mbakerrest] today. \r\n\r\nSo... am I missing a more elegant RESTful way of doing this which doesn't result in a quadrillion HTTP requests?\r\n\r\n[mbakerrest]: http://www.markbaker.ca/Talks/2004-xmlself/all.htm\r\n\r\n\r\n ",
"parentPath": "./content/posts/archives/2004",
"path": "2004/09/15/manipulating-aggregate-resources-in-a-rest-api",
"needsBuild": true,
"prevPostPath": "2004/09/13/dbagg3alive",
"prevPostTitle": "Early dbagg3 demo is alive and kicking",
"nextPostPath": "2004/09/16/moving-time-from-cvs-to-subversion",
"nextPostTitle": "Moving time: From CVS to Subversion"
} ![](\"http://www.gravatar.com/avatar.php?gravatar_id=e873edb1d1943ea7087468439ce64d37&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\"/)
\r\n Trevor F. Smith\r\n Even the most stringent of REST advocates will break down and use reasonable parameters for adjectives, adverbs and unusual qualifiers. Leave the path for nouns and verbs.\r\n \r\n \r\n \r\n ![](\"http://www.gravatar.com/avatar.php?gravatar_id=ad3bec4560b1c5d0ffddddc497c8b1e0&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\"/)
\r\n Jeremy Dunck\r\n PUT /aggregates/312,443,523\r\n\r\n1\r\n\r\n---\r\n\r\nGET /aggregates/1/now-12.xml\r\n \r\n \r\n \r\n ![](\"http://www.gravatar.com/avatar.php?gravatar_id=b9ed774661a22ff8797a1e0e24f0baf3&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\"/)
\r\n Robert Sayre\r\n Lessons from WebDAV\r\n \r\n \r\n \r\n ![](\"http://www.gravatar.com/avatar.php?gravatar_id=4654316e8388b2e83af98a3118d976bb&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\"/)
\r\n Andrew Shearer\r\n Interesting method, Jeremy.\r\n\r\nThe revised GET request looks closer to the REST philosophy to me than the original. The thing that worries me is that now you're generating state on the server (a new \"aggregate resource\" with its own identifier), and it's not clear that it's needed. How long does the server have to keep the list around? Could other clients access it if they guessed the ID?\r\n\r\nIt's the PUT request that causes the problems. It's a high price to pay for a modest improvement in the GET request.\r\n\r\nOn second thought, I don't see much wrong with the original. URLs can be algorithmic, and this one just happens to refer to a list of things. The thing that throws it into a different mental category for me is probably the combinatorial explosion. But does it really matter that now, for practical purposes, the REST service could no longer be fully indexed by search engines?\r\n \r\n \r\n \r\n ![](\"http://www.gravatar.com/avatar.php?gravatar_id=266511c4b3124a981ccd3b1716e0bb0b&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\"/)
\r\n Buzz Andersen\r\n I've wondered about this in the context of an application I'm designing that allows wildcard queries (e.g. /id/1*/details.html) as part of the URL path. To me, it seems OK to do that, from REST's \"document-centric\" viewpoint, since it seems reasonable that I could actually have an actual document with that path. Your original GET request seems like the same thing to me.\r\n\r\nI could be completely wrong though--I'd be the first to admit that I still find REST a bit difficult to pin down. It seems like it's a lot like the old saw about pornography: I can't define it, but I know it when I see it :-).\r\n \r\n \r\n \r\n ![](\"http://www.gravatar.com/avatar.php?gravatar_id=cc8334869c9d2a9e603017f2da805eb3&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\"/)
\r\n Ian Bicking\r\n To expand on WebDAV, certain WebDAV operations produce compound requests and responses, all packaged in XML. I can't remember what they look like, but it's really nothing more than several HTTP requests packaged in XML. They use it for doing atomic operations on several files/resources. It's kind of REST, kind of anti-REST.\r\n\r\nOtherwise, of course, the query string is reasonably unordered and allows multiple pieces of data, i.e., /subscriptions/now-12.xml?id=1&id=2&id=3\r\n\r\nAnother option is to somehow define sets. E.g., something like POST /createset (request body contains the IDs) and then the server responds with an identifier for that set, and then you work with that identifier.\r\n \r\n \r\n \r\n ![](\"http://www.gravatar.com/avatar.php?gravatar_id=d0d0148e03ff9f1639cab8b35bf625db&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\"/)
\r\n Ken Meltsner\r\n You could have the system return an existing identifier as the response to sending it a set of identifiers, if that set has already been defined.\r\n\r\nThat is, treat the GET as more of a \"return existing or create a new one\" operation. And if you want to be really consistent, allow sets to include other sets.\r\n\r\n\r\nPerhaps something like:\r\n\r\nGET /setID/entries/12322,12326,12325,12388,12412\r\n\r\nwould return \r\n\r\n912345678\r\n\r\nthe first time and all following times, and then 912345678 could be used from then on.\r\n\r\nI think this would be idempotent, cache-friendly, etc.\r\n \r\n \r\n \r\n ![](\"http://www.gravatar.com/avatar.php?gravatar_id=05a5272a087ce9a44bd5f050932d7a28&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\"/)
\r\n Mark Baker\r\n Yah, REST isn't ideal for dealing with sets of resources since most operations on sets are specific to sets and therefore not uniform. Consider the equivalent of a \"FILL\" operation, which would be a PUT on everything in a set of resources, where the set was identified by the HTTP Request-URI.\r\n\r\nWebDAV can help with its collections stuff, but sometimes that's overkill. When I've encountered this, I've simply created a resource for the set and a POST on it changes the state of all the members of the set. Not RESTful, but so long as you understand the architectural consequences, that's ok.\r\n \r\n \r\n \r\n
Archived Comments
\n\n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=e873edb1d1943ea7087468439ce64d37&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nTrevor F. Smith\n \n\n\n \n\n\nEven the most stringent of REST advocates will break down and use reasonable parameters for adjectives, adverbs and unusual qualifiers. Leave the path for nouns and verbs. \n\n\n \n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=ad3bec4560b1c5d0ffddddc497c8b1e0&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nJeremy Dunck\n \n\n\n \n\n\nPUT /aggregates/312,443,523\n1\n---\nGET /aggregates/1/now-12.xml \n\n\n \n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=b9ed774661a22ff8797a1e0e24f0baf3&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nRobert Sayre\n \n\n\n \n\n\nLessons from WebDAV \n\n\n \n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=4654316e8388b2e83af98a3118d976bb&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nAndrew Shearer\n \n\n\n \n\n\nInteresting method, Jeremy.\nThe revised GET request looks closer to the REST philosophy to me than the original. The thing that worries me is that now you're generating state on the server (a new \"aggregate resource\" with its own identifier), and it's not clear that it's needed. How long does the server have to keep the list around? Could other clients access it if they guessed the ID?\nIt's the PUT request that causes the problems. It's a high price to pay for a modest improvement in the GET request.\nOn second thought, I don't see much wrong with the original. URLs can be algorithmic, and this one just happens to refer to a list of things. The thing that throws it into a different mental category for me is probably the combinatorial explosion. But does it really matter that now, for practical purposes, the REST service could no longer be fully indexed by search engines? \n\n\n \n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=266511c4b3124a981ccd3b1716e0bb0b&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nBuzz Andersen\n \n\n\n \n\n\nI've wondered about this in the context of an application I'm designing that allows wildcard queries (e.g. /id/1*/details.html) as part of the URL path. To me, it seems OK to do that, from REST's \"document-centric\" viewpoint, since it seems reasonable that I could actually have an actual document with that path. Your original GET request seems like the same thing to me.\nI could be completely wrong though--I'd be the first to admit that I still find REST a bit difficult to pin down. It seems like it's a lot like the old saw about pornography: I can't define it, but I know it when I see it :-). \n\n\n \n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=266511c4b3124a981ccd3b1716e0bb0b&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nBuzz Andersen\n \n\n\n \n\n\nUpon further reading: isn't Jeremy's method wrong per Paul Prescod's \"Common REST Mistakes\" (http://www.prescod.net/rest/mistakes/)? In particular:\n\"Do not invent proprietary object identifiers.\"\nAnd...\n\"If you use URI syntax with UUIDs or something like that then you get half of the benefit of URIs. You get a standardized syntax but have no standardized dereferencing capability.\"\nEssentially, only the client that did the post and stored the ID in Jeremy's example would have a way of referencing that set.\nAm I wrong? \n\n\n \n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=cc8334869c9d2a9e603017f2da805eb3&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nIan Bicking\n \n\n\n \n\n\nTo expand on WebDAV, certain WebDAV operations produce compound requests and responses, all packaged in XML. I can't remember what they look like, but it's really nothing more than several HTTP requests packaged in XML. They use it for doing atomic operations on several files/resources. It's kind of REST, kind of anti-REST.\nOtherwise, of course, the query string is reasonably unordered and allows multiple pieces of data, i.e., /subscriptions/now-12.xml?id=1&id=2&id=3\nAnother option is to somehow define sets. E.g., something like POST /createset (request body contains the IDs) and then the server responds with an identifier for that set, and then you work with that identifier. \n\n\n \n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=d0d0148e03ff9f1639cab8b35bf625db&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nKen Meltsner\n \n\n\n \n\n\nYou could have the system return an existing identifier as the response to sending it a set of identifiers, if that set has already been defined.\nThat is, treat the GET as more of a \"return existing or create a new one\" operation. And if you want to be really consistent, allow sets to include other sets.\nPerhaps something like:\nGET /setID/entries/12322,12326,12325,12388,12412\nwould return \n912345678\nthe first time and all following times, and then 912345678 could be used from then on.\nI think this would be idempotent, cache-friendly, etc. \n\n\n \n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=05a5272a087ce9a44bd5f050932d7a28&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nMark Baker\n \n\n\n \n\n\nYah, REST isn't ideal for dealing with sets of resources since most operations on sets are specific to sets and therefore not uniform. Consider the equivalent of a \"FILL\" operation, which would be a PUT on everything in a set of resources, where the set was identified by the HTTP Request-URI.\nWebDAV can help with its collections stuff, but sometimes that's overkill. When I've encountered this, I've simply created a resource for the set and a POST on it changes the state of all the members of the set. Not RESTful, but so long as you understand the architectural consequences, that's ok. \n\n\n \n- \n
\n\n![](\"http://www.gravatar.com/avatar.php?gravatar_id=ad3bec4560b1c5d0ffddddc497c8b1e0&size=32&default=http://mediacdn.disqus.com/1320279820/images/noavatar32.png\")
\nJeremy Dunck\n \n\n\n \n\n\nI'm not a well-experienced, RESTian. Thanks for the pointer to Prescod's piece.\nI was thinking what Ken later said (Sep 16 @ 3:31PM). \n\n\n \n
\n\n\n\n
\n
\n
\n
\n
\n
\n
\n
\n
\n