On Apr 30, 2008, at 10:20 PM, Nick Gall wrote:
> "Not clear what Bob's software is doing"? Do you really believe
> that, Mark? I think it's pretty darn clear what the TAG thinks the
> software is doing:
>
>
> "Bob if he views the source of the form is assured that the
> assigning authority issupporting an entire class of URIs of the
> form: http://example.org/cityweather?city=CityName. ... Bob could,
> with this assurance, write his ownsoftware to construct and use
> such URIs to retrieve weather reports."
>
> The TAG is clearly not suggesting that Bob is merely authorized by
> the FORM to write generic FORM-parsing software as you suggest. On
> the contrary, It is clearly stating that given the specific
> "weather URI" parameters that appear in the FORM, Bob is authorized
> to write software that can generate "an entire class of URIs" "to
> retrieve weather reports". In other words the software can use a
> URI template.

I don't see why we should care.  Anyone is "authorized" to write any
software.
Anyone is authorized to perform a GET on any URI.  The server will
respond
however it sees fit.  The document got stuck in the weeds somewhere and
is struggling to make sense out of nonsense.

Don't read too much into what is obviously a poor choice of words.
What they meant to say is that some services correspond to a range
(template) of URIs for which guessing the potential values in that
range is a perfectly reasonable thing to do, even if there turns
out to be no resource for a given guess.  There are no guarantees
on the Web.

....Roy

The HTML form is just one way of discovering a RESTful "service" or,
better named, a family of resources with a commen URL pattern (which
hopefully is expressable in URI templates). A friend sending you the
uri template or telling you about it in suaheli are other ways to
discover the same thing.

If that is worth the investement to hard-code that in software is
entirely up to you.

//Stefan

resources with structure
inviting retrieval of content
- cache control.

Am 01.05.2008 um 07:20 schrieb Nick Gall:

> On Thu, May 1, 2008 at 12:12 AM, Mark Baker <distobj@...> wrote:
> > I would hope that the software Bob is writing just parses the form,
> > and doesn't assume the URI structure will remain static for all
> time.
> > It's not clear what Bob's software is doing there though, so it
> could
> > probably use a clarification.
>
> "Not clear what Bob's software is doing"? Do you really believe
> that, Mark? I think it's pretty darn clear what the TAG thinks the
> software is doing:
>
>
> "Bob if he views the source of the form is assured that the
> assigning authority issupporting an entire class of URIs of the
> form: http://example.org/cityweather?city=CityName. ... Bob could,
> with this assurance, write his ownsoftware to construct and use
> such URIs to retrieve weather reports."
>
> The TAG is clearly not suggesting that Bob is merely authorized by
> the FORM to write generic FORM-parsing software as you suggest. On
> the contrary, It is clearly stating that given the specific
> "weather URI" parameters that appear in the FORM, Bob is authorized
> to write software that can generate "an entire class of URIs" "to
> retrieve weather reports". In other words the software can use a
> URI template.
>
> > Why don't you bring it up with them?
>
> Good idea. I wanted to check with this group to see if I was just
> confused about the finding before going to the TAG. Plus, I am
> hoping some of them will read my post here and respond. If they
> don't, I'll forward a part of the thread to them.
>
> I'll suggest that if they do intend that the mere appearance of a
> FORM in an HTML representation assures a developer that the FORM's
> parameters will be long lived enough to justify writing URI-
> template-processing software based on them, then the TAG should
> publish a "cool FORMs don't change" good practice finding to
> clarify their intent.
>
> -- Nick
>
>

--
<green/>bytes GmbH, Hafenweg 16, D-48155 Münster, Germany
Amtsgericht Münster: HRB5782

On Thu, 2008-05-01 at 00:20 -0700, Roy T. Fielding wrote:
> Don't read too much into what is obviously a poor choice of words.
> What they meant to say is that some services correspond to a range
> (template) of URIs for which guessing the potential values in that
> range is a perfectly reasonable thing to do, even if there turns
> out to be no resource for a given guess. There are no guarantees
> on the Web.

If you have a hypermedia application client/agent that interprets the
resources it receives and then uses that resource as the basis for
determining the available state transitions supported by the server, why
would you need to bother with guessing (or relying on a URI template)
for an automated agent?

Maybe I'm wrong, but I see URI templates as a pragmatic shortcut so that
agent authors don't need to bother with interpreting the hypermedia they
receive.  This makes writing agents more in line with standard modes of
thinking about software design and implementation, e.g. to accomplish a
task, you make calls to functions with known parameters in an order
determined by the caller to trigger state transitions and/or receive
some expected output.

However, if that's the way you approach development of a hypermedia
application where the service has the opportunity - by design - to tell
you about the available state transitions and the location of other
resources that it thinks are related/relevant to the current resource,
how is your agent really part of a hypermedia application?

As Nick pointed out, there aren't many systems out there that do this
(interactive Web browsers being a notable exception).  I think this is
one of the drivers for the sem-web initiatives, but I also think there's
value in trying to leverage this approach today to build more robust
software systems that can gracefully handle changes in the service
implementation.

ast
--
Andrew S. Townley <ast@...>
http://atownley.org

Andrew S. Townley wrote:
>
> Maybe I'm wrong, but I see URI templates as a pragmatic shortcut so that
> agent authors don't need to bother with interpreting the hypermedia they
> receive. This makes writing agents more in line with standard modes of
> thinking about software design and implementation, e.g. to accomplish a
> task, you make calls to functions with known parameters in an order
> determined by the caller to trigger state transitions and/or receive
> some expected output.

Well, it may be that many people use URI templates as a shortcut for
using hypermedia but there *are* valid uses of URI templates that do
not entail cheating.

For example, in the application on which I work tracks time series
data for a large number of metrics.  Each metric is a resource, as is
the observations for those metrics.  Many (non-browser) agents need all
the observations from specific time frames to perform their work.  To
facilitate this we have provided a "link" in the metric
representations to any time based subset of the observations for that
metric using a template. For example,

http://foo.example/metrics/232/observations?start={start_time}&end={end_time}

This works quite well for us, and I cannot think of any other approach
that would be as efficient and simple.  It is worth noting that we do
not guarantee that URL will exist in the future.  Rather, we guarantee
that there will be a URL template in the metric representations that
you can substitute `start_time` and `end_time` into and use get the
set of observation in that time frame.

Peter Williams
http://pezra.barelyenough.org

On Thu, 2008-05-01 at 08:51 -0600, Peter Williams wrote:
> Andrew S. Townley wrote:
> >
> > Maybe I'm wrong, but I see URI templates as a pragmatic shortcut so that
> > agent authors don't need to bother with interpreting the hypermedia they
> > receive. This makes writing agents more in line with standard modes of
> > thinking about software design and implementation, e.g. to accomplish a
> > task, you make calls to functions with known parameters in an order
> > determined by the caller to trigger state transitions and/or receive
> > some expected output.
>
> Well, it may be that many people use URI templates as a shortcut for
> using hypermedia but there *are* valid uses of URI templates that do
> not entail cheating.
>
> For example, in the application on which I work tracks time series
> data for a large number of metrics.  Each metric is a resource, as is
> the observations for those metrics.  Many (non-browser) agents need all
> the observations from specific time frames to perform their work.  To
> facilitate this we have provided a "link" in the metric
> representations to any time based subset of the observations for that
> metric using a template. For example,
>
> http://foo.example/metrics/232/observations?start={start_time}&end={end_time}
>
> This works quite well for us, and I cannot think of any other approach
> that would be as efficient and simple.  It is worth noting that we do
> not guarantee that URL will exist in the future.  Rather, we guarantee
> that there will be a URL template in the metric representations that
> you can substitute `start_time` and `end_time` into and use get the
> set of observation in that time frame.

Hi Peter,

So, are you saying that you embed the template in the representation
for
http://foo.example/metrics/232?  If so, why wouldn't you just put a 2
field form there instead?  I agree that it means you don't have the
ability to just make one request.  If the template's in the resource
anyway, I would see the form as being less work to ensure you were
constructing the correct URIs because the representation+form would do
it for you automatically.

Cheers,

ast
--
Andrew S. Townley <ast@...>
http://atownley.org

Andrew S. Townley wrote:
>> For example, in the application on which I work tracks time series
>> data for a large number of metrics.  Each metric is a resource, as is
>> the observations for those metrics.  Many (non-browser) agents need all
>> the observations from specific time frames to perform their work.  To
>> facilitate this we have provided a "link" in the metric
>> representations to any time based subset of the observations for that
>> metric using a template. For example,
>>
>> http://foo.example/metrics/232/observations?start={start_time}&end={end_time}
>
> So, are you saying that you embed the template in the representation
> for
> http://foo.example/metrics/232?  If so, why wouldn't you just put a 2
> field form there instead?  I agree that it means you don't have the
> ability to just make one request.  If the template's in the resource
> anyway, I would see the form as being less work to ensure you were
> constructing the correct URIs because the representation+form would do
> it for you automatically.


The main reason is that the representations I am thinking of are JSON
documents that look a bit like this:

      {
       "_type": "Metric",
       "observations_in_interval_href":
"http://foo.example/metrics/232/observations?start={start_time}&end={end_time}",
      }

(There are lots of other attributes of course.)  So using a form is not
really a very appealing option.  However, we do implement this as a two
field form in the HTML representations.

Hope that clears up the confusion.

--
Peter Williams
http://pezra.barelyenough.org

1. I infer from "we do not guarantee that [any observation interval] URL will exist in the future" that you've decided that such URLs should be considered ephemeral, ie not "cool URLs". Since cool URLs are good practice according to the AWWWv1 and TBL, can you share the thinking behind not following good practice? Would users never want to bookmark such observation intervals?
2. I assume that the URLs to the metrics are cool, eg http://foo.example/metrics/232/ . If not, what is the cool URL that bootstraps me into the system and how do I navigate to metric URLs like this one? And again, why was the decision made to not follow good practice by making metric URL ephemeral.
3. I am trying to measure the coupling of your approach in terms of fixed points: dependencies that must be established "out of band" before the client and server can share information. In other words, these are long-lived, static dependencies that are NOT dynamically and ephemerally established in the course of a sequence of request/replies between the client and server. I count five fixed points required to access an observation interval using the indirect method you describe:
   
1. the metric authority:http://foo.example/
2. the metric relative URL: metrics/232/
3. the JSON name/value pair for the URL template: observations_in_interval_href: <template>
   
4. the template variable name: start_time
5. the template variable name: stop_time
4. Direct use of an observation interval template alone has only four fixed points:
1. the observation authority: http://foo.example/
2. the observations relative URL: /metrics/232/observations?
3. the URL argument name: start
4. The URL argument name: end
5. Given that your approach has more fixed point dependencies than a simple direct use of a URL, can you explain what dependencies you were trying to eliminate and why? For example, is observations_in_interval_href less likely to change than /metrics/232/observations? Is start_time less likely to change than start?

On Thu, 2008-05-01 at 16:01 -0400, Nick Gall wrote:

> As I wrote this up, it dawned on me that establishing the use of
> server-generated ephemeral URLs in returned representations as a good
> practice is effectively contradicting the cool URL good practice. The
> former seeks to minimize the number of cool (long lived) URLs and the
> latter practice seeks to maximize them. Put another way, proponents of
> server-generated ephemeral URLs appear to believe that long-lived URLs
> are not cool because they create long-lived dependencies.
>
> So which is the better design -- a hypermedia application rich in long
> lived URLs or a hypermedia application poor in long lived URLs, just a
> few "bootstrap" URLs? Up til now I always assumed the former, but now
> I'm not so sure. Again this reminds me a bit of the deep-linking
> debate, eg a building with many doors vs a building with few doors.

That reminds me, I meant to get back to your earlier question to me
about deep linking.  In the approach I was talking about, deep linking
isn't an issue, because either way, the service should give you an
"out", i.e. a navigable state transition URI regardless of whether it
gives you the page you expected or not.  As long as you "bookmarked" or
otherwise saved a URI that was given to you from the service, it follows
what I was trying to specify via my definition of hypermedia.

I hadn't thought about the cache header point that Mark made earlier,
but I like the idea of using it as a hint.  Even if you tried to
dereference it after it expires, the service will hopefully give you a
navigable resource instead--even if it's an error page with a pointer to
the "front door".

Personally, I think that if you're only using the URIs presented to you
from the server (or the 'friendly' ones printed on the side of a bus
which are bound to be *a* 'front door' if not *the* 'front door'), then
you can bookmark any URI you like.  My issue is with URI generation or
"guessing" in the case of automated agents; it's less about the TTL of
the particular URI.  However, the TTL is more relevant if you're going
to use template-based approaches and you don't want your system to break
in the face of changes in the service.

ast
--
Andrew S. Townley <ast@...>
http://atownley.org

On Thu, May 1, 2008 at 4:01 PM, Nick Gall <nick.gall@...> wrote:
> I infer from "we do not guarantee that [any observation interval] URL will
> exist in the future" that you've decided that such URLs should be considered
> ephemeral, ie not "cool URLs".

Those URLs might very well be cool, but there's just no way to
communicate that (IIRC HTTP has a 1 year age limit - a good thing).
But declaring a space of them in an HTML form that expires in a week
doesn't mean they're *not* cool.

Mark.
--
Mark Baker. Ottawa, Ontario, CANADA. http://www.markbaker.ca
Coactus; Web-inspired integration strategies http://www.coactus.com

On May 1, 2008, at 2:03 AM, Andrew S. Townley wrote:
> On Thu, 2008-05-01 at 00:20 -0700, Roy T. Fielding wrote:
> > Don't read too much into what is obviously a poor choice of words.
> > What they meant to say is that some services correspond to a range
> > (template) of URIs for which guessing the potential values in that
> > range is a perfectly reasonable thing to do, even if there turns
> > out to be no resource for a given guess. There are no guarantees
> > on the Web.
>
> If you have a hypermedia application client/agent that interprets the
> resources it receives and then uses that resource as the basis for
> determining the available state transitions supported by the
> server, why
> would you need to bother with guessing (or relying on a URI template)
> for an automated agent?
>

For the same reason that you would bother using Google search.
Look in the HTTP spec for the phrase "all modern information
systems ...".

> Maybe I'm wrong, but I see URI templates as a pragmatic shortcut so
> that
> agent authors don't need to bother with interpreting the hypermedia
> they
> receive. This makes writing agents more in line with standard modes of
> thinking about software design and implementation, e.g. to
> accomplish a
> task, you make calls to functions with known parameters in an order
> determined by the caller to trigger state transitions and/or receive
> some expected output.
>

That's one way to use them, yes.  The other way is computed links.

> However, if that's the way you approach development of a hypermedia
> application where the service has the opportunity - by design - to
> tell
> you about the available state transitions and the location of other
> resources that it thinks are related/relevant to the current resource,
> how is your agent really part of a hypermedia application?
>

Again, the other way is computed links (see hypertext research).

> As Nick pointed out, there aren't many systems out there that do this
> (interactive Web browsers being a notable exception). I think this is
> one of the drivers for the sem-web initiatives, but I also think
> there's
> value in trying to leverage this approach today to build more robust
> software systems that can gracefully handle changes in the service
> implementation.
>

There are many systems that use computed links.  Almost all of the
closed-world hypertext systems had automated dictionary lookup
(click on any non-linked word and it retrieves the dictionary
entry for that word).  Programming IDEs do much the same.  A template
is just a way for a server to tell a client that there is a range
of resources available -- just like server-side image maps, HTML
forms, and (in less visible ways) javascript.  As long as the template
is defined by the server, they are still links.  As long as the template
is defined by the server in a recent representation, it is RESTful.

....Roy

On Thu, 2008-05-01 at 14:03 -0700, Roy T. Fielding wrote:
> On May 1, 2008, at 2:03 AM, Andrew S. Townley wrote:
> > On Thu, 2008-05-01 at 00:20 -0700, Roy T. Fielding wrote:
> >
> > If you have a hypermedia application client/agent that interprets
> the
> > resources it receives and then uses that resource as the basis for
> > determining the available state transitions supported by the
> > server, why
> > would you need to bother with guessing (or relying on a URI
> template)
> > for an automated agent?
> >
>
> For the same reason that you would bother using Google search.
> Look in the HTTP spec for the phrase "all modern information
> systems ...".

Sorry for being thick, but I'm not quite sure the point you're trying to
make here.  The closest I could find was in 1.1 Purpose:

         "Practical information systems require more functionality than
         simple retrieval, including search, front-end update, and
         annotation."

Is that what you meant?  If so, I understand that and agree, but I still
don't get your point, sorry...

> > As Nick pointed out, there aren't many systems out there that do
> this
> > (interactive Web browsers being a notable exception). I think this
> is
> > one of the drivers for the sem-web initiatives, but I also think
> > there's
> > value in trying to leverage this approach today to build more robust
> > software systems that can gracefully handle changes in the service
> > implementation.
> >
>
> There are many systems that use computed links. Almost all of the
> closed-world hypertext systems had automated dictionary lookup
> (click on any non-linked word and it retrieves the dictionary
> entry for that word). Programming IDEs do much the same. A template
> is just a way for a server to tell a client that there is a range
> of resources available -- just like server-side image maps, HTML
> forms, and (in less visible ways) javascript. As long as the template
> is defined by the server, they are still links. As long as the
> template
> is defined by the server in a recent representation, it is RESTful.

Thanks for the pointer to the computed links concept.  It's been a
couple years since I read much of the hypertext research, and I didn't
remember this.  With a quick google, I found this paper that looked
pretty relevant:  "Hand-made and Computed Links, Precomputed and Dynamic
Links (1997)" (http://citeseer.ist.psu.edu/161116.html).  From the
introduction:

         "This paper surveys the use of hand-made and computed links in
hypermedia systems and
         contrasts precomputation and dynamic computation of those links which
are computed.
         This paper seeks to raise all the issues in one place, so that designers
of hypermedia
         systems can consider the issues together, whether they can afford to
ignore some forms of
         link, which forms are the most suitable to their working environment,
and so on."

Based on a quick skim of the paper, I guess I should qualify my
uneasiness about URI templates.  I can see how the server could specify
a URI template in the resource it sends to allow computed links (for
dictionary, glossary or other types of lookup) using JavaScript or
something like XForms and an agreement about what the form did as part
of the specification of the content model.  In effect, as you say, it's
functionally equivalent to an HTML form, because the form effectively
defines the template as stated by the recommendation Nick referenced.

This use of template URIs still wouldn't bother me because they would be
defined (potentially) dynamically by the server and be a part of the
representation used by the client.  Since they're part of the hypermedia
that must be processed by the client to accomplish any state transition,
I 100% agree that they would, in fact, be RESTful.

However, I see URI templates defined in a different resource -
especially out-of-band API documentation - as a totally different beast.
Admittedly, I only did a quick skim of the paper and a couple of other
sources, but I would find it a bit of a stretch to say that these could
be considered computed links of the same kind.  By their very nature,
aren't they documented so that they can become part of the client's
implementation rather than having it use the information in the resource
from the service?  The template isn't defined by the server at all in
this case, right, so how can this use of template URIs be RESTful?

Thanks again for the reference.

ast
--
Andrew S. Townley <ast@...>
http://atownley.org

Hi,

I'm still trying to figure rest out. Let's see if I hit a sweet spot
or if I'm just missing something (more likely, please forgive me).

I have several images, each with its own uri that have metadata.
If I want to update the metadata of a given image I send a POST
request on its uri. Right?
What if I want to atomically update some metadata (say, a tag) for a
group of images, how do I approach that?
Sending multiple POST requests, one for each uri, is not atomic, so I
can't accept it.

I thought about posting on the common parent of all the image uris
(say, if I have /images/1, /images/2, etc., then I post on /images).
In the parameters of the post request I would put a list of all the
imaged ids (or entire uri), so that the server can handle the request
atomically.

But then what should I get in return? What should /images return if I
issued a GET? The whole repository? Naaa... too big.
Isn't the POST supposed to return the same representation? Just after
handling the posted request.

How much am I missing from the rest picture?

Thanks
Stefano

On Fri, May 2, 2008 at 4:56 PM, Stefano Masini
<stefano.masini@...> wrote:
> Hi,
>
>  I'm still trying to figure rest out. Let's see if I hit a sweet spot
>  or if I'm just missing something (more likely, please forgive me).
>
>  I have several images, each with its own uri that have metadata.
>  If I want to update the metadata of a given image I send a POST
>  request on its uri. Right?
>  What if I want to atomically update some metadata (say, a tag) for a
>  group of images, how do I approach that?
>  Sending multiple POST requests, one for each uri, is not atomic, so I
>  can't accept it.

First, it sounds like you want PUT, not POST.  PUT means "create or
replace the entity"; POST means "accept this entity as a child".  What
you want to do here is GET the full representation, make whatever
changes you want, then PUT the whole thing back.  It's a
"read-modify-write" operation.

>  I thought about posting on the common parent of all the image uris
>  (say, if I have /images/1, /images/2, etc., then I post on /images).
>  In the parameters of the post request I would put a list of all the
>  imaged ids (or entire uri), so that the server can handle the request
>  atomically.

I'd define a way to refer to a specific set of images.  Say you want
to modify images 1, 4, and 13.  You can PUT (and GET) to
"/images/1,4,13" with an entity fully describing three images.  This
is just like your proposed idea, except you're referring to a limited
set of images instead of all of them.  The server then atomically
replaces images 1, 4, and 13 with the entities you provided.

One thing to note is that URIs like this require more complex linking.
  The client needs to be able to construct those "1,4,13" URIs somehow,
but it must be told how to, at runtime, by the server; otherwise it
would violate HATEoAS.  You need a way to say something like <a
href="/images/\d(,\d)*">, where the href there is actually a regex
describing how to build a URI out of a series of integers.  Maybe
someone else can chime on how to do this well, because I have no idea.
  I do know that you do *not* want to actually use regexes, though. :)

>  But then what should I get in return? What should /images return if I
>  issued a GET? The whole repository? Naaa... too big.
>  Isn't the POST supposed to return the same representation? Just after
>  handling the posted request.

This question is answered by the limited-subset solution above.  When
you GET "/images/1,4,13", you get back exactly what you'd expect -
images 1, 4, and 13, just as they were when you PUT them in.

>  How much am I missing from the rest picture?

Well, the PUT/POST thing, but everyone makes that mistake at first. :)
I think another thing people often miss is that the URI space doesn't
have to be rigid or static.  That's exactly the issue here.  What
you're trying to do is modify a subset of a collection, so just say it
in the URI! :)

--
Gary
http://blog.extracheese.org

For the case of image tags (like flickr, etc.) maybe you could expose
the tags as resources. Then if you want to add the tag "chunkybacon"
to a set of images, you could POST to e.g. /tag/chunkybacon/ an
entity-body with the list of the URIs of images you want to add the
tag. Of course if you GET /tag/chunkybacon/ you'll see a
representation of a list of all chunkybacon images so far.

A similar trick using lists is to expose a list of all image tags
under /images/<id>/tags; then you can POST multiple tags to a single
image. A more complex application would be to support image sets at
URI level, like "/images/<id1>;<id2>;<id3>"; then you can POST
multiple tags to multiple images at "/images/<id1>;<idN>/tags"... You
got the idea. Whatever method you use, be sure to link to or create
forms to it elsewhere.

Side note: the "list URIs" above, as a not-much-known convention, use
"," as separator when order matters and ";" when it doesn't. Note also
that URIs have a maximum lenght.



On 5/2/08, Gary Bernhardt <gary.bernhardt@...> wrote:
> On Fri, May 2, 2008 at 4:56 PM, Stefano Masini
> <stefano.masini@...> wrote:
> > Hi,
> >
> >  I'm still trying to figure rest out. Let's see if I hit a sweet spot
> >  or if I'm just missing something (more likely, please forgive me).
> >
> >  I have several images, each with its own uri that have metadata.
> >  If I want to update the metadata of a given image I send a POST
> >  request on its uri. Right?
> >  What if I want to atomically update some metadata (say, a tag) for a
> >  group of images, how do I approach that?
> >  Sending multiple POST requests, one for each uri, is not atomic, so I
> >  can't accept it.
>
> First, it sounds like you want PUT, not POST.  PUT means "create or
> replace the entity"; POST means "accept this entity as a child".  What
> you want to do here is GET the full representation, make whatever
> changes you want, then PUT the whole thing back.  It's a
> "read-modify-write" operation.
>
> >  I thought about posting on the common parent of all the image uris
> >  (say, if I have /images/1, /images/2, etc., then I post on /images).
> >  In the parameters of the post request I would put a list of all the
> >  imaged ids (or entire uri), so that the server can handle the request
> >  atomically.
>
> I'd define a way to refer to a specific set of images.  Say you want
> to modify images 1, 4, and 13.  You can PUT (and GET) to
> "/images/1,4,13" with an entity fully describing three images.  This
> is just like your proposed idea, except you're referring to a limited
> set of images instead of all of them.  The server then atomically
> replaces images 1, 4, and 13 with the entities you provided.
>
> One thing to note is that URIs like this require more complex linking.
>  The client needs to be able to construct those "1,4,13" URIs somehow,
> but it must be told how to, at runtime, by the server; otherwise it
> would violate HATEoAS.  You need a way to say something like <a
> href="/images/\d(,\d)*">, where the href there is actually a regex
> describing how to build a URI out of a series of integers.  Maybe
> someone else can chime on how to do this well, because I have no idea.
>  I do know that you do *not* want to actually use regexes, though. :)
>
> >  But then what should I get in return? What should /images return if I
> >  issued a GET? The whole repository? Naaa... too big.
> >  Isn't the POST supposed to return the same representation? Just after
> >  handling the posted request.
>
> This question is answered by the limited-subset solution above.  When
> you GET "/images/1,4,13", you get back exactly what you'd expect -
> images 1, 4, and 13, just as they were when you PUT them in.
>
> >  How much am I missing from the rest picture?
>
> Well, the PUT/POST thing, but everyone makes that mistake at first. :)
> I think another thing people often miss is that the URI space doesn't
> have to be rigid or static.  That's exactly the issue here.  What
> you're trying to do is modify a subset of a collection, so just say it
> in the URI! :)
>
> --
> Gary
> http://blog.extracheese.org
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

--
Sent from Google Mail for mobile | mobile.google.com

Leonardo Boiko
http://namakajiri.net

On Fri, May 2, 2008 at 8:31 PM, Leonardo Boiko <leoboiko@...> wrote:
>  Side note: the "list URIs" above, as a not-much-known convention, use
>  "," as separator when order matters and ";" when it doesn't. Note also
>  that URIs have a maximum lenght.

The specs don't have any URI length restrictions, but current browsers
do, so it depends on what your client is.  BitBacker, the system I've
used this technique in, regularly generates URLs over 10,000
characters long.  This works fine, since both the server and client
sides are prepared to deal with that.  However, it can get very
annoying when manually reading the log files. :)

--
Gary
http://blog.extracheese.org

Nick Gall wrote:
>    1. I infer from "we do not guarantee that [any observation interval]
>       URL will exist in the future" that you've decided that such URLs
>       should be considered ephemeral, ie not "cool URLs". Since cool
>       URLs are good practice according to the AWWWv1 and TBL, can you
>       share the thinking behind not following good practice? Would users
>       never want to bookmark such observation intervals?

In practice these URLs are "cool", I suppose.  When we change the shapes
of URLs we always implement redirections from the old to the new shapes.

My statement about them not being guaranteed arose from the fact that we
encourage automated agents not store URLs unless it is absolutely
necessary.  That policy is mostly about avoiding having many URLs in the
wild that are obsolescent and taking the multi request overhead of
redirection.

>    2. I assume that the URLs to the metrics are cool, eg
>       http://foo.example/ metrics/232/ <http://foo.example/metrics/232/>
>       . If not, what is the cool URL that bootstraps me into the system
>       and how do I navigate to metric URLs like this one? And again, why
>       was the decision made to not follow good practice by making metric
>       URL ephemeral.

As with observations, any particular metric URL will be supported for a
long time.  However that longevity may be achieved by the use of
redirection should we need to change the disposition of the resource.

As for how to navigate to the metric, we have implemented a resource
discovery mechanism which we generally use as the main entry point.  I
have describing it at
http://pezra.barelyenough.org/blog/2008/01/restful-service-discovery-and-descrip\
tion/
if you are interested.

>    3. I am trying to measure the coupling of your approach in terms of
>       fixed points: dependencies that must be established "out of band"
>       before the client and server can share information. In other
>       words, these are long-lived, static dependencies that are NOT
>       dynamically and ephemerally established in the course of a
>       sequence of request/replies between the client and server. I count
>       five fixed points required to access an observation interval using
>       the indirect method you describe:
>          1. the metric authority:http://foo.example/
>          2. the metric relative URL: metrics/232/
>          3. the JSON name/value pair for the URL template: observations_
>             in_interval_ href: <template>
>          4. the template variable name: start_time
>          5. the template variable name: stop_time

I am not sure I would count 1 and 2 as separate.  I generally conceive
of URLs as atomic entities.  Other than that it looks about right.


>    4. Direct use of an observation interval template alone has only four
>       fixed points:
>          1. the observation authority: http://foo.example/
>          2. the observations relative URL: /metrics/232/ observations?
>          3. the URL argument name: start
>          4. The URL argument name: end
>    5. Given that your approach has more fixed point dependencies than a
>       simple direct use of a URL, can you explain what dependencies you
>       were trying to eliminate and why? For example, is observations_
>       in_interval_ href less likely to change than /metrics/232/
>       observations? Is start_time less likely to change than start?

The main thing we were trying to achieve is to allow the server a great
deal of freedom in the disposition of resources.  For example, if a
server becomes overloaded we need the freedom to relocate the
observations for any metrics we choose.  While we can, and do, continue
to support obsolesce URLs via redirection, having the original location
of the resource forced to handle the initial requests and redirection is
less optimal than just having agents go to the right place in the first
place.

>
> As I wrote this up, it dawned on me that establishing the use of
> server-generated ephemeral URLs in returned representations as a good
> practice is effectively contradicting the cool URL good practice. The
> former seeks to minimize the number of cool (long lived) URLs and the
> latter practice seeks to maximize them. Put another way, proponents of
> server-generated ephemeral URLs appear to believe that long-lived URLs
> are not cool because they create long-lived dependencies.
>
> So which is the better design -- a hypermedia application rich in long
> lived URLs or a hypermedia application poor in long lived URLs, just a
> few "bootstrap" URLs? Up til now I always assumed the former, but now
> I'm not so sure. Again this reminds me a bit of the deep-linking debate,
> eg a building with many doors vs a building with few doors.

I tend to prefer having as few long lived URLs as possible.  Each long
lived URL represents an additional maintenance burden for the system
over time.   In my experience, however, it turns out that most URLs in a
system do need to be long lived.  It is probably easier and safer to
just assume that all the URLs in a system will have to be supported for
a very long time.

--
Peter Williams
http://pezra.barelyenough.org

Microsoft has proposed a bulk format so you can process all your requests in
one go, using multipart messages as the payload, with each message being an
http request. That way you can PUT on each of those resources in one go if
you so wish.

See:

http://blogs.msdn.com/astoriateam/archive/2008/04/06/batching-data-service-r
equests.aspx

I'm not sure yet what I think about that proposal  but it certainly does
solve the problem of batching requests much better than http pipelining does
it.

And I personally find the whole POSt to http://server/resource/1,2,3,4 to be
akward, with low visibility and discoverability, but that's a matter of
taste :)

SerialSeb
-----Original Message-----
From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On
Behalf Of Stefano Masini
Sent: 02 May 2008 21:56
To: rest-discuss@yahoogroups.com
Subject: [rest-discuss] Updating metadata of multiple resources

Hi,

I'm still trying to figure rest out. Let's see if I hit a sweet spot
or if I'm just missing something (more likely, please forgive me).

I have several images, each with its own uri that have metadata.
If I want to update the metadata of a given image I send a POST
request on its uri. Right?
What if I want to atomically update some metadata (say, a tag) for a
group of images, how do I approach that?
Sending multiple POST requests, one for each uri, is not atomic, so I
can't accept it.

I thought about posting on the common parent of all the image uris
(say, if I have /images/1, /images/2, etc., then I post on /images).
In the parameters of the post request I would put a list of all the
imaged ids (or entire uri), so that the server can handle the request
atomically.

But then what should I get in return? What should /images return if I
issued a GET? The whole repository? Naaa... too big.
Isn't the POST supposed to return the same representation? Just after
handling the posted request.

How much am I missing from the rest picture?

Thanks
Stefano

------------------------------------

Yahoo! Groups Links

On Sat, May 3, 2008 at 12:04 PM, Sebastien Lambla <seb@...> wrote:
> Microsoft has proposed a bulk format so you can process all your requests in
>  one go, using multipart messages as the payload, with each message being an
>  http request. That way you can PUT on each of those resources in one go if
>  you so wish.
>
>  See:
>
>  http://blogs.msdn.com/astoriateam/archive/2008/04/06/batching-data-service-r
>  equests.aspx
>
>  I'm not sure yet what I think about that proposal  but it certainly does
>  solve the problem of batching requests much better than http pipelining does
>  it.
>
>  And I personally find the whole POSt to http://server/resource/1,2,3,4 to be
>  akward, with low visibility and discoverability, but that's a matter of
>  taste :)

By definition, it's either discoverable or it's not REST.  If the
representation linking to that resource tells the client how to
construct the URL, it's fully discoverable.  If it fails to tell the
client how, then the client has no way to construct the URL at all
without violating HATEoAS.

Now, if by "low visibility and discoverability" you mean "doesn't
conform directly to the rigid 1990s view of the URL space", then sure.
  REST does require a bit of a mental leap.  But I don't find "REST is
hard, let's go shopping!" a very convincing argument. :)

I've thought a lot about the idea of nesting multiple requests in a
multipart payload.  The more I've come to understand REST, the less
useful that technique has seemed.  If examples like the one above are
motivating it, it's tremendous overkill.  The URL space does not have
to be rigid!  Free your mind! :)

--
Gary
http://blog.extracheese.org

On Sat, May 3, 2008 at 1:04 PM, Sebastien Lambla <seb@...> wrote:
> That way you can PUT on each of those resources in one go if
>  you so wish.

I don't feel that PUT is a natural way of assign "folksonomy" tags to
pictures; POSTing tag URIs to an image resource or vice-versa feels
more "right" to me.  But it may be just me.

--
Leonardo Boiko
http://namakajiri.net

>So which is the better design -- a hypermedia application rich in
long lived URLs or a >hypermedia application poor in long lived URLs,
just a few "bootstrap" URLs?

Hypermedia as the engine of application state!
Hypermedia as the engine of application state!
HATEOAS induces loose coupling in your network application. This
causes interesting stuff in your application like anarchic scalability
etc. etc. (see Roy's Thesis). Thus you want to use HATEOAS, as much as
you can. You WANT to try and use the links / hrefs as much as
possible. Its just nice software engineering to decouple your client
and servers from each other.

"When we think about WS-* style services, there's little notion of
graphs of information resources. One exchanges documents with
embedded, "managed" data identifiers, like primary keys. The client
has to maintain the context of what the identifier signifies and know
the provider's assumptions in how, when, and where the identifier
should be accessed. All of these assumptions are tacit, and hence,
tightly coupled."[1]

Cool URIs are a nice etiquette . But do NOT put this above your basic
requirement viz. building an application that will scale to the web
and be able to live on the web (for which it will need various
interesting properties .. again see the REST-bible :)

The whole thrust of the "cool uris don't change" note , was that it is
frustrating for humans to see a dangling or broken link. But this
won't be the case if you are building a bot / your own application
that traverses your network based application.

While I have concentrated on Scalability till now , you know that on
the net it is ANARCHIC scalability. There are NO guarentees and it is
wrong of you to assume any (even if some "best practices" document
tells you to).

[1] http://www.stucharlton.com/blog/archives/000141.html

Regards
Devdatta

On 02/05/2008, Nick Gall <nick.gall@...> wrote:
>
>
>
>
>
>
> On Thu, May 1, 2008 at 10:51 AM, Peter Williams <pezra@...>
wrote:
> > For example, in the application on which I work tracks time series
> > data for a large number of metrics. Each metric is a resource, as is
>  > the observations for those metrics. Many (non-browser) agents need all
> > the observations from specific time frames to perform their work. To
> > facilitate this we have provided a "link" in the metric
>  > representations to any time based subset of the observations for that
> > metric using a template. For example,
> >
> >
http://foo.example/metrics/232/observations?start={start_time}&end={end_time}
>  >
> > This works quite well for us, and I cannot think of any other approach
> > that would be as efficient and simple. It is worth noting that we do
> > not guarantee that URL will exist in the future. Rather, we guarantee
>  > that there will be a URL template in the metric representations that
> > you can substitute `start_time` and `end_time` into and use get the
> > set of observation in that time frame.
>
> An elegant approach. A couple of observations/questions:
>
>
> I infer from "we do not guarantee that [any observation interval] URL will
exist in the future" that you've decided that such URLs should be considered
ephemeral, ie not "cool URLs". Since cool URLs are good practice according to
the AWWWv1 and TBL, can you share the thinking behind not following good
practice? Would users never want to bookmark such observation intervals?
> I assume that the URLs to the metrics are cool, eg
http://foo.example/metrics/232/ . If not, what is the cool URL that bootstraps
me into the system and how do I navigate to metric URLs like this one? And
again, why was the decision made to not follow good practice by making metric
URL ephemeral.
> I am trying to measure the coupling of your approach in terms of fixed points:
dependencies that must be established "out of band" before the client and server
can share information. In other words, these are long-lived, static dependencies
that are NOT dynamically and ephemerally established in the course of a sequence
of request/replies between the client and server. I count five fixed points
required to access an observation interval using the indirect method you
describe:
>
>
> the metric authority:http://foo.example/
> the metric relative URL: metrics/232/
> the JSON name/value pair for the URL template: observations_in_interval_href:
<template>
>
> the template variable name: start_time
> the template variable name: stop_time
> Direct use of an observation interval template alone has only four fixed
points:
>
> the observation authority: http://foo.example/
> the observations relative URL: /metrics/232/observations?
> the URL argument name: start
> The URL argument name: end
> Given that your approach has more fixed point dependencies than a simple
direct use of a URL, can you explain what dependencies you were trying to
eliminate and why? For example, is observations_in_interval_href less likely to
change than /metrics/232/observations? Is start_time less likely to change than
start? As I wrote this up, it dawned on me that establishing the use of
server-generated ephemeral URLs in returned representations as a good practice
is effectively contradicting the cool URL good practice. The former seeks to
minimize the number of cool (long lived) URLs and the latter practice seeks to
maximize them. Put another way, proponents of server-generated ephemeral URLs
appear to believe that long-lived URLs are not cool because they create
long-lived dependencies.
>
> So which is the better design -- a hypermedia application rich in long lived
URLs or a hypermedia application poor in long lived URLs, just a few "bootstrap"
URLs? Up til now I always assumed the former, but now I'm not so sure. Again
this reminds me a bit of the deep-linking debate, eg a building with many doors
vs a building with few doors.
>
> -- Nick
>
>
>

> I don't feel that PUT is a natural way of assign "folksonomy" tags to
> pictures; POSTing tag URIs to an image resource or vice-versa feels
> more "right" to me.  But it may be just me.

Metadata is probably a resource about a resource, so it could be said that it is
in itself a resource that can be PUT to for updates, or POSTed to the image as a
sub resource (rather than a child as I've seen it called earlier).

Same could be said about rdf documents

--
SerialSeb

      - Annotation of existing resources;


      - Posting a message to a bulletin board, newsgroup, mailing list,
        or similar group of articles;

      - Providing a block of data, such as the result of submitting a
        form, to a data-handling process;


      - Extending a database through an append operation.

> By definition, it's either discoverable or it's not REST.  If the
> representation linking to that resource tells the client how to
> construct the URL, it's fully discoverable.  If it fails to tell the
> client how, then the client has no way to construct the URL at all
> without violating HATEoAS.

I fail to see how the server can instruct the client in any meaningful way
that urls in the form of http://server/resource/1,2,3,4 represent a pool of
documents equal to /resource/1, /resource/2 etc. If you want to set that
convention up thats fine with me, but it's just that, a convention specific
to the way you define your service, and in that it is opaque with low
discoverability.

> REST does require a bit of a mental leap.  But I don't find "REST is
> hard, let's go shopping!" a very convincing argument. :)

I don't believe I'm making this argument, quite the contrary. The solution
you seem to be promoting isn't more rest than batching requests in one go
through a multipart message. At least with that solution the semantics of
Urls are respected and still general purpose, as opposed to
convention-driven url construction.

> The URL space does not have to be rigid!  Free your mind! :)

They have to be discoverable and not built by private conventions. I don't
believe in the value of transient composite Urls that have only meaning when
in the context of the documentation of your service, be it that it is 1,2,3
or 1;2;3.

If you start doing /1,2,3 supporting POST that translates in 3 POSTS to /1,
/2 and /3, do you support a GET on the same conventional URL? If not you
don't have a uniform interface anymore. If you do, you cannot support things
like ETags, caching etc, unless you do it as a collection.

Overall it seems to me it introduces more mess than it solves issues.

--
SerialSeb

(Apologies for top posting; my response was getting huge and
fragmented, so I summarized.)

Let's get specific.  If you're going to implement my method, you need
a new media type.  Here's one possible implementation.  Call it
"text/html-with-javascript-links".  We add an extension to the <a> tag
so you can do things like this:

<a href="javascript:function(ids) { return '/resources/' + ids.join(','); }">

That little javascript function will return a string of the form
"/resources/1,2,3,4" when called with the list [1, 2, 3, 4].  This is
still perfectly RESTful, because the server is telling the client
exactly how to construct the URL.  This is not a "convention" any more
than HTML forms are; it's just another media type.  It's not "specific
to my service" because, once again, it's a (hypothetical) standard
media type.  If you support it once, you support it for every service.
  It's not "opaque" or "undiscoverable" because you have to have a
priori knowledge of it to even negotiate for a representation in the
first place.

It's also *much* simpler to implement than the proposed multi-part
request solution.  Current clients support neither of the proposed
methods.  I happen to be most familiar with Python's httplib, and I
can say without a doubt that multi-part requests would require serious
changes, since you can no longer make the assumption that HTTP
requests are of the form "send request, then block until the response
comes".  Httplib makes exactly that assumption.

Contrast that with my proposed solution - all you're doing is
constructing the URL a little differently.  There are no underlying
HTTP library changes.  I can testify that this is very simple to do,
because I'm doing it right now, in a production system!  It took maybe
an hour to add my first aggregate resource, and most of that time was
spent on the server-side business logic.  It's been in production for
about six months and I've not given it a thought since; it's always
just worked.  The media-type issues are separate, of course; I haven't
tackled them yet.

Aside from implementation complexity, the multi-part request solution
breaks HTTP in numerous subtle ways.  It throws "one request, one
response" out the window.  It also brings up thorny questions, like
"What happens if the 47th request in the series fails?  How do you
tell the client?  How does he recover?"  The client now has a
fragmented concept of an "HTTP request" - sometimes a request is a
request; sometimes a request is actually a batch of requests.  This
will trickle its way down into the client logic, not just the HTTP
library.

The application programmer will have to *explicitly* batch requests.
When he's batching request #13 out of 17, what is his current state?
What is the representation of that state?  He sure as heck didn't get
it from the server!  If your client states don't correspond one-to-one
with representations from the server, you're not doing
"representational state transfer"; you're just doing "state transfer"!
  It ain't REST! :)

There's also the fundamental question of which method to use for your
multi-part request.  Do you use POST?  What if the batch of requests
is made up only of DELETEs?  Is "delete these 57 resources" within the
definition of POST?  Do you really have a uniform interface at that
point, or is your multi-part request really RPC in disguise?  These
are the questions that made me back away from the "multi-part request"
technique, although it was initially tempting.

Sometimes widening your solution space a little is easier than digging
1,000 feet deeper into the hole you're already in. :)

--
Gary
http://blog.extracheese.org

On Sat, May 3, 2008 at 1:48 PM, Sebastien Lambla <seb@...> wrote:
> > By definition, it's either discoverable or it's not REST.  If the
>  > representation linking to that resource tells the client how to
>  > construct the URL, it's fully discoverable.  If it fails to tell the
>  > client how, then the client has no way to construct the URL at all
>  > without violating HATEoAS.
>
>  I fail to see how the server can instruct the client in any meaningful way
>  that urls in the form of http://server/resource/1,2,3,4 represent a pool of
>  documents equal to /resource/1, /resource/2 etc. If you want to set that
>  convention up thats fine with me, but it's just that, a convention specific
>  to the way you define your service, and in that it is opaque with low
>  discoverability.
>
>
>  > REST does require a bit of a mental leap.  But I don't find "REST is
>  > hard, let's go shopping!" a very convincing argument. :)
>
>  I don't believe I'm making this argument, quite the contrary. The solution
>  you seem to be promoting isn't more rest than batching requests in one go
>  through a multipart message. At least with that solution the semantics of
>  Urls are respected and still general purpose, as opposed to
>  convention-driven url construction.
>
>
>  > The URL space does not have to be rigid!  Free your mind! :)
>
>  They have to be discoverable and not built by private conventions. I don't
>  believe in the value of transient composite Urls that have only meaning when
>  in the context of the documentation of your service, be it that it is 1,2,3
>  or 1;2;3.
>
>  If you start doing /1,2,3 supporting POST that translates in 3 POSTS to /1,
>  /2 and /3, do you support a GET on the same conventional URL? If not you
>  don't have a uniform interface anymore. If you do, you cannot support things
>  like ETags, caching etc, unless you do it as a collection.
>
>  Overall it seems to me it introduces more mess than it solves issues.

> Let's get specific.  If you're going to implement my method, you need
> a new media type.  Here's one possible implementation.  Call it
> "text/html-with-javascript-links".


This is where I think we differ: I believe infrastructure issues should be
dealt at the infrastructure level, not pushed at the app level. By defining
your javascript / html, you are rest, no doubt about it. But you do not
solve the problem of sending a whole bunch of requests that you would like
see processed in one block.

What is not provided in either solutions is to decide the behaviour on
failure: Updating on resources 1,2,3 would may fail for resource 2. What
happens then? Stop all of them, considering 1,2,3 were modified in one
transaction? Do you continue to 3 even though 2 failed? Do you stop at 2 and
leave 1 having been modified? And how do you communicate the result? By
wrapping several changes in one url, you can leverage the http status code
only in an atomic fashion, which may or may not be what your application
needs. The multipart approach lets you differentiate should you need it, and
only buy into the atomic change when and if you need it.

> [...] This is not a "convention" any more
> than HTML forms are; it's just another media type.  It's not "specific
> to my service" because, once again, it's a (hypothetical) standard
> media type.

You may well be right in the sense that you rely on an informational
resource to tell you how to construct a url. That said, I fail to see how
this could be implemented easily in most toolkits: you rely on either having
prior knowledge or executing javascript. In that respect I don't see the
difference between your solution and the multipart one.

> If you support it once, you support it for every service.

I don't understand this assertion? Surely, any solution you come up with
will be generalizable to any resource, be it pipelining extended to
PUT/POST, multipart or your javascript-based URL building?

> It's not "opaque" or "undiscoverable" because you have to have a
> priori knowledge of it to even negotiate for a representation in the
> first place.

You need to understand the resource type, just like you need to understand
the batch multipart format, so in this respect I don't think you're adding
much value.

> It's also *much* simpler to implement than the proposed multi-part
> request solution.  Current clients support neither of the proposed
> methods.

It may be a bit simpler to implement, but multipart mime is a known format
with plenty of supporting libraries supporting it. In itself it wouldn't
take much to support that bulk format from javascript, but certainly much
more than your solution.

>  since you can no longer make the assumption that HTTP
> requests are of the form "send request, then block until the response
> comes".  Httplib makes exactly that assumption.

I'm not sure we're talking about hte same proposal. All the requests are
sent in one go, and all the response are received in one go. On the wire you
have a simple request / response, so you can still do blocking stuff.

>  It throws "one request, one
> response" out the window.

I don't understand how does it do that? You still get one response per
request, they just happened to be sent and received in bulk?

> "What happens if the 47th request in the series fails?

See my point earlier: this is the space of convention in both solutions.

> [...] sometimes a request is a
> request; sometimes a request is actually a batch of requests.

See above, n requests => n responses, this doesn't change this. What changes
is that you transmit all your requests as a payload.

> The application programmer will have to *explicitly* batch requests.
> When he's batching request #13 out of 17, what is his current state?

You assume that each set of changes is dependent on the new representation
you get after the previous operation. When you update the two picture's
metadata, you will receive an updated representation or a 204, be it that
you did a bulk update through url construction or through bulking the
requests. I really fail to see how your solution would be REST and the
multipart would only be ST, as the only difference is that you rely on
understanding a specific representation to build infrastructure bulk
changes, and multipart would rely on... The same thing! without the need for
the transient urls.

> There's also the fundamental question of which method to use for your
> multi-part request.  Do you use POST?  What if the batch of requests
> is made up only of DELETEs?  Is "delete these 57 resources" within the
> definition of POST?  Do you really have a uniform interface at that
> point, or is your multi-part request really RPC in disguise?  These
> are the questions that made me back away from the "multi-part request"
> technique, although it was initially tempting.

That is certainly a shortcoming of the current solution and I agree with
you: is defining a _service_ called $batch supporting a post and always
returing a 200 the right thing to do? I'm not bothered too much about the
operations that are contained in the payload, as this url serves essentially
as a proxy to execute all the attached requests as if they were individual.

> Sometimes widening your solution space a little is easier than digging
> 1,000 feet deeper into the hole you're already in. :)

You assume that the batching requirements can be resolved simply by
combining resources of a same type and building transient uri through a
language sent down to the client, and that all those operations will always
be one operation and one type of operation. That's a lot of assumptions that
don't necessarily apply. This is a good solution for the small scope of the
issue that was presented though, but it doesn't resolve the more global
problem of batching a bunch of operations against n resources without
issuing n connections and waiting for the response n*m seconds.

In that respect the multipart approach solves the same kind of issues Http
pipelining should have solved for GET, as well as provide a way to group a
bunch of http operations in one unit of work.

That said the solution doesn't make me feel warm and fuzzy inside, but
neither does yours.

--
SerialSeb

While this approach looks better than pipelining, it is more like SOAP
than HTTP. What is the difference between this, and say, packaging the
same parts as some XML elements inside some envelope element?

Regards,
Subbu

On May 3, 2008, at 9:04 AM, Sebastien Lambla wrote:
> Microsoft has proposed a bulk format so you can process all your
> requests in
> one go, using multipart messages as the payload, with each message
> being an
> http request. That way you can PUT on each of those resources in one
> go if
> you so wish.
>
> See:
>
> http://blogs.msdn.com/astoriateam/archive/2008/04/06/batching-data-service-r
> equests.aspx
>
> I'm not sure yet what I think about that proposal  but it certainly
> does
> solve the problem of batching requests much better than http
> pipelining does
> it.
>
> And I personally find the whole POSt to http://server/resource/
> 1,2,3,4 to be
> akward, with low visibility and discoverability, but that's a matter
> of
> taste :)
>
> SerialSeb
> -----Original Message-----
> From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com
> ] On
> Behalf Of Stefano Masini
> Sent: 02 May 2008 21:56
> To: rest-discuss@yahoogroups.com
> Subject: [rest-discuss] Updating metadata of multiple resources
>
> Hi,
>
> I'm still trying to figure rest out. Let's see if I hit a sweet spot
> or if I'm just missing something (more likely, please forgive me).
>
> I have several images, each with its own uri that have metadata.
> If I want to update the metadata of a given image I send a POST
> request on its uri. Right?
> What if I want to atomically update some metadata (say, a tag) for a
> group of images, how do I approach that?
> Sending multiple POST requests, one for each uri, is not atomic, so I
> can't accept it.
>
> I thought about posting on the common parent of all the image uris
> (say, if I have /images/1, /images/2, etc., then I post on /images).
> In the parameters of the post request I would put a list of all the
> imaged ids (or entire uri), so that the server can handle the request
> atomically.
>
> But then what should I get in return? What should /images return if I
> issued a GET? The whole repository? Naaa... too big.
> Isn't the POST supposed to return the same representation? Just after
> handling the posted request.
>
> How much am I missing from the rest picture?
>
> Thanks
> Stefano
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>
>

> While this approach looks better than pipelining, it is more like SOAP
> than HTTP. What is the difference between this, and say, packaging the
> same parts as some XML elements inside some envelope element?

Several benefits:
- Multipart messages are a standard way to represent compound payloads
- You don't enforce the use of xml

If you were to compound those requests in a specific xml document, you need
to define a custom mime type rather than reuse an existing one, force the
understanding of the compound payload on the consumer, and you will end up
having to represent the semantics of multiple requests by serializing your
http message in one way or another, at which point it makes more sense from
my perspective to just package the message in its natural format
(application/http is defined in rfc2616).

Where you are right is that the $batch is the definition of a service, and
some would argue that services have no place in a rest architecture, because
all visible area should be resources. I don't think it's inherently bad to
have some resources be services that have no semantic value, I am just
concerned that you lose a lot of discoverability and you create orthogonal
concerns when dealing with an API.

To be clear on my position on this proposal: I really like the idea of
multipart of application/http and get the result in the same format. I am
however not certain I like the semantics of the $batch url and the semantics
associated with that endpoint, how discoverable it is and how knowledge of
the transfer and format is sent to the client, so it's mixed reaction from
me. But I don't like other proposals for the reasons i've invoked in my
previous emails and the inherent flexibility of the multipart approach is
very seductive.

--
SerialSeb

Without consulting any writings or people, describe the uniform
interface in REST. Consider your effort a charitable act toward a
layperson.

--
Etan Wexler.

P.S. To maintain the thread in various user agents, please leave
"[rest-discuss]" at the end of the subject field. Feel free to curse
Yahoo Groups.

First of all thank you all for the great responses this thread got.
They were very helpful to a starter like me. So thank you.

But now let me get this straight. I hope you'll forgive my naive questions.

On Sun, May 4, 2008 at 2:39 AM, Sebastien Lambla <seb@...> wrote:
>  > than HTML forms are; it's just another media type. It's not "specific
>  > to my service" because, once again, it's a (hypothetical) standard
>  > media type.
>
>  You may well be right in the sense that you rely on an informational
>  resource to tell you how to construct a url. That said, I fail to see how
>  [...]

I'll hook up here, and try to go back to my original example.

So I think I understand (and like) the principle of discoverability,
in the sense that the client should not be held responsible to come up
with urls. Instead it should somehow be told about them by the server.
The client remains responsible for is the _why_ a given url is needed,
but the _how_ is told by the server. Good.

So, back to my image repository example: let's assume that the
preferred representation is Json and that the client wants to make use
of a url identifying a given set of images. Gary proposed an approach
making use of a "text/html-with-javascript-links" media type, with the
representation being some html containing a javascript code snippet.
My first question: can I safely translate that proposal to my example
by rewriting that code snippet as the following Json data structure?
{
   imageSetUrlBuilder: "function(ids) { return '/resources/' + ids.join(','); }"
}

The client application, of course, should know how to deal with such
information, just like it should know about the
text/html-with-javascript-links media type, or anything else. I'd say,
it actually _expects_ it, rather than just knowing how to deal with
it.

Now my second question: which part of my url space is better suited
for containing this piece of Json?
If I think about it, it seems like some sort of application global
"information". It's a piece of functionality (in the form of a
javascript code snippet) that the client app needs to fetch right at
the beginning in order to be fully functional. So, I'd say, the root
url (/) is the best place, together with all the other stuff I might
like to include in the root url, i.e. the one representing my
application in general, including other urls. For example:
{
   imageSetUrlBuilder: "function(ids) { return '/resources/' + ids.join(','); }",
   allImagesUrl: "/images",
   title: "My fancy application"
}

What do you think? Am I beginning to see more RESTy? :)

Thanks
Stefano