Hey all,

I was wondering about the best way to RESTfully model information
retrievals versus queries in REST.  Imagine an Artist structure with
name, genre, albums, rating, etc.  I want to both search for Artists
that approximate the name or albums, or exactly match a genre or
rating.  As well, I want to retrieve a given Artist's information.

The retrieval is easy, with something like GET /Artist?
name=thieverycorp retrieving the structure.

But then if want to do a search, I was thinking the best rest way of
modeling is to make a Query structure that contains all the Artist
queryable information, maybe it's even the same type, and then have
an ArtistList resource.  Then I could say that any of the ArtistQuery
fields can be put in the URI, ie
GET /ArtistList?name=thieverycorp or GET /ArtistList?albums=blue.

I can't see a way of using the same URI base for both retrievals and
queries without doing some funky parameters in the URI.  There's a
variety of other techniques, like appending the requested return type
(GET /Artist?name=thieverycorp&type=ArtistList), the number of
results to return (GET /Artist?name=thieverycorp&rows=1), etc. but
they all seem a bit .... goofy.

Any help on the best way to model this would be appreciated.  I'm
pretty sure this is almost an FAQ kind of question, so even a pointer
would be great.

Thanks,
Dave Orchard

----- Original Message -----
From: "dorchard100" <orchard@...>
To: <rest-discuss@yahoogroups.com>
Sent: Tuesday, June 01, 2004 1:33 PM
Subject: [rest-discuss] Re-using information fields for queries in REST


| Hey all,
|
| I was wondering about the best way to RESTfully model information
| retrievals versus queries in REST.  Imagine an Artist structure with
| name, genre, albums, rating, etc.  I want to both search for Artists
| that approximate the name or albums, or exactly match a genre or
| rating.  As well, I want to retrieve a given Artist's information.
|
| The retrieval is easy, with something like GET /Artist?
| name=thieverycorp retrieving the structure.

That looks more like a collection or subset to me.  A single
artist resource might be more like /Artist/123.  An important
question is: how does the client discover that URI?  The "hyptertext
engine" constraint of REST really wants it to be discovered, not
fabricated by client as a parameter list.


|
| But then if want to do a search, I was thinking the best rest way of
| modeling is to make a Query structure that contains all the Artist
| queryable information, maybe it's even the same type, and then have
| an ArtistList resource.  Then I could say that any of the ArtistQuery
| fields can be put in the URI, ie
| GET /ArtistList?name=thieverycorp or GET /ArtistList?albums=blue.

I would have called it /Artists?prop=value,..., but that's just
naming preference.


|
| I can't see a way of using the same URI base for both retrievals and
| queries without doing some funky parameters in the URI.

URI's are cheap, and so then are URI bases.  Why the need
for such economy?

There's a
| variety of other techniques, like appending the requested return type
| (GET /Artist?name=thieverycorp&type=ArtistList), the number of
| results to return (GET /Artist?name=thieverycorp&rows=1), etc. but
| they all seem a bit .... goofy.

All stemming from a false sense of URI conservation, right?

If your application really needs to hide the distinction between
a single resource and a collection of that resource "type",
then you could try an Alloy trick: treat instances as singleton
sets.

That would mean there are only queries, no retrievals (to use
your lingo), and when a query returns a single result, blow right
past the list representation to the individual.  I don't know how
RESTful or unRESTful that would be.  I suspect it's neither.

|
| Any help on the best way to model this would be appreciated.  I'm
| pretty sure this is almost an FAQ kind of question, so even a pointer
| would be great.
|
| Thanks,
| Dave Orchard


Walden

Hi Dave,

The best way is to have the query do just that -- present a list
of query results.  If you actually want it to direct the client to
a single match, then send a redirect to that match.  The resources
themselves should be independently named from any query that you do,
even if that means simply redirecting them to something dull like

     /Artist/id/12345678

....Roy

> Well, how did I do? Is that even close to the truth?
>
> Regards
> Donald.

BTW, Donald, sorry to have taken so long to post a response, your
message ended up in my spam bin somehow.  Not speaking for other folks,
but I think you did a fine job of summarizing.  My only caveat is that
sending diffs around / processing them is useful when there's a LOT of
data of a relatively opaque form, but the cost is clarity and
simplicity;  in smaller cases (such as the example) and perhaps most
applications of document-oriented XML messaging in general --- I'm not
sure the benefit is worth the cost.  But that's more a subjective style
thing than anything else.

Also NB:  per the If-Match:  entity tags?  Full-on versioning of every
reified resource seems onerous.  Don't know if that was implied or not,
but a hash or randomly generated token per version or date of last mod
or transaction sequence number or any number of other tokens could be
used as entity tags w/ the same effect.  IMHO, versioning per se is a
rather centralized and brittle mechanism --- particularly for an
application like preventing simple update collisions.  And IMHO, given
all the additional semantics of versioning per se, if you're going that
route you might as well completely reify the whole version tree in
URIspace.

jb

> -----Original Message-----
> From: Walden Mathews [mailto:walden@...]
> | I was wondering about the best way to RESTfully model information
> | retrievals versus queries in REST.  Imagine an Artist
> structure with
> | name, genre, albums, rating, etc.  I want to both search
> for Artists
> | that approximate the name or albums, or exactly match a genre or
> | rating.  As well, I want to retrieve a given Artist's information.
> |
> | The retrieval is easy, with something like GET /Artist?
> | name=thieverycorp retrieving the structure.
>
> That looks more like a collection or subset to me.  A single
> artist resource might be more like /Artist/123.  An important
> question is: how does the client discover that URI?  The "hyptertext
> engine" constraint of REST really wants it to be discovered, not
> fabricated by client as a parameter list.

Why is discovery of a particular URI "better" than discovery of the construction
technique for a URI?  This argues that HTML FORM GETs are a bad way of creating
URIs because they are fabricated.

Cheers,
Dave

-----Original Message-----
From: Walden Mathews [mailto:walden@...]
That looks more like a collection or subset to me. A single
artist resource might be more like /Artist/123. An important
question is: how does the client discover that URI? The "hyptertext
engine" constraint of REST really wants it to be discovered, not
fabricated by client as a parameter list.

Why is discovery of a particular URI "better" than discovery of the construction technique for a URI? This argues that HTML FORM GETs are a bad way of creating URIs because they are fabricated.

> Why is discovery of a particular URI "better" than discovery of the
> construction technique for a URI?  This argues that HTML FORM GETs are
> a bad way of creating URIs because they are fabricated.

Caching.  If you already have the information for that artist,
why should you be forced to download it again?  Often, the reason
is because the resource provider just assumes every access is a
query by a new user on a home PC with broadband, because that is
the only way they have ever tested their own site.

The query URI is still a valid identifier for the query -- it just
isn't as useful, alone, for enhancing scalability.  A redirection
allows an infinite number of queries to be redirected to a finite
number of resources, each of which can be cached.  [Note: special
purpose caches can be created on the server-side for handling
common queries, as is done by Google and big e-commerce sites, but
that only improves back-end performance.]

Anyway, we are talking about resource discovery over arbitrary
data categories, and hence non-hierarchical in nature.  There is
nothing wrong with telling the client how it can form URI's,
assuming that such a function doesn't change much over time.
Again, for cache reasons, I prefer methods of telling the client
to use the template

     http://example.com/quotes/${exchange}/${symbol}

rather than the template

     http://example.com/quotes?market=${exchange}&symbol=${symbol}

There is nothing stopping WSDL-like technology from defining
both of these mechanisms.

....Roy

Meant to send this to the list...

WM

----- Original Message -----
From: "Walden Mathews" <walden@...>
To: "David Orchard" <orchard@...>
Sent: Tuesday, June 01, 2004 7:46 PM
Subject: Re: [rest-discuss] Re-using information fields for queries in REST


: Dave,
:
: : > That looks more like a collection or subset to me.  A single
: : > artist resource might be more like /Artist/123.  An important
: : > question is: how does the client discover that URI?  The "hyptertext
: : > engine" constraint of REST really wants it to be discovered, not
: : > fabricated by client as a parameter list.
: :
: : Why is discovery of a particular URI "better" than discovery of the
: construction technique for a URI?  This argues that HTML FORM GETs are a
bad
: way of creating URIs because they are fabricated.
: :
:
: It depends on what you're trying to do, and how much error you're
: willing to tolerate.
:
: You use GET FORMs to identify sets of resources, where the form
: fields correspond to the bound variables of a set comprehension.  And
: when you search like that, you have one set of expectations, including
: the possibility that you'll find nothing.
:
: In a different context, the one we were discussing above where you
: are trying to retrieve a known individual, a URI formula or construction
: technique would only introduce uncertainty, whereas an immutable
: string id is just the ticket.
:
: To put that concept to the test, consider how much you'd like the web
: if all the links were replaced by forms that required you to type naming
: minutiae without error, in order to progress.
:
: Your question is interesting: it caused me to think about to what degree
: forms qualify as "hypertext".  Does anyone have an opinion on that?
:
: Walden
:

Gotcha on the use of hierarchy rather than flat where appropriate.

> -----Original Message-----
> From: Roy T. Fielding [mailto:fielding@...]

<snip/>
> Anyway, we are talking about resource discovery over arbitrary
> data categories, and hence non-hierarchical in nature.  There is
> nothing wrong with telling the client how it can form URI's,
> assuming that such a function doesn't change much over time.
> Again, for cache reasons, I prefer methods of telling the client
> to use the template
>
>     http://example.com/quotes/${exchange}/${symbol}
>
> rather than the template
>
>     http://example.com/quotes?market=${exchange}&symbol=${symbol}
>
> There is nothing stopping WSDL-like technology from defining
> both of these mechanisms.
>
> ....Roy
>

Hey, now there's an idea.  Maybe even official WSDL technology...

Cheers,
Dave

-----Original Message-----
From: Seairth Jacobs [mailto:seairth@...]
Sent: Tuesday, June 01, 2004 4:54 PM
To: rest-discuss
Subject: Re: [rest-discuss] Re-using information fields for queries in REST

"David Orchard" wrote:

-----Original Message-----
From: Walden Mathews [mailto:walden@...]
That looks more like a collection or subset to me. A single
artist resource might be more like /Artist/123. An important
question is: how does the client discover that URI? The "hyptertext
engine" constraint of REST really wants it to be discovered, not
fabricated by client as a parameter list.

Why is discovery of a particular URI "better" than discovery of the construction technique for a URI? This argues that HTML FORM GETs are a bad way of creating URIs because they are fabricated.

Suppose you defined the semantics of the query response format to provide such constraints/rules necessary to construct URIs.  As long as the client understands the semantics of the format, you are basically where HTML forms are.  However, just listing the URIs themselves would be much more straight forward.  The URI is an opaque identifier.  As such, the client can stay dumb and loosely coupled.  If, at some later time, you should choose to change the URI construction (say from /artist/123 to /artist/tu123 or /a23423992359652), the client continues working unchanged.  The constructed URI approach, on the other hand, would be brittle.  You would either need to construct your URIs in a backward-compatible manner or require the clients to learn the new construction rules, neither of which are a very desirable choice.

Suppose you want to reference artists on another site that uses an entirely different URI format.  Are you going to reverse-engineer those URIs and add yet more semantics to the query response format for those URIs?

Also, there's a propensity for humans to see patterns in structures.  URIs are often such a structure.  I agree that a person seeing /artist/123 may be inclined to try artist/124.  However, I think people are more inclined to see /artist?id=123 and try /artist?id=124.  The moment you tell people that there is a pattern, they expect the pattern.  You can't stop people from seeing patterns where there may not be any, but you can certainly stop from telling people there is a pattern where you know there is not one.

--
Seairth Jacobs

On Tue, Jun 01, 2004 at 05:47:54PM -0700, David Orchard wrote:
> Gotcha on the use of hierarchy rather than flat where appropriate.
>
> > -----Original Message-----
> > From: Roy T. Fielding [mailto:fielding@...]
>
> <snip/>
> > Anyway, we are talking about resource discovery over arbitrary
> > data categories, and hence non-hierarchical in nature.  There is
> > nothing wrong with telling the client how it can form URI's,
> > assuming that such a function doesn't change much over time.
> > Again, for cache reasons, I prefer methods of telling the client
> > to use the template
> >
> >     http://example.com/quotes/${exchange}/${symbol}
> >
> > rather than the template
> >
> >     http://example.com/quotes?market=${exchange}&symbol=${symbol}
> >
> > There is nothing stopping WSDL-like technology from defining
> > both of these mechanisms.
> >
> > ....Roy
> >
>
> Hey, now there's an idea.  Maybe even official WSDL technology...

*groan*  Ok, sure, *now* you support my "make WSDL more form-like"
suggestions. 8-)

The new HTTP binding goes further in this direction, but still falls
short largely because it bumps up against the *very* different demands
of a forms language compared with an interface description language.

I'd personally prefer to start over with a forms language, which is
why I created RDF Forms; http://www.markbaker.ca/2003/05/RDF-Forms/ .
But it has a bit of legacy in its support of www-form-urlencoded
serializations for POST bodies and URIs largely because that's what
server APIs easily support and it's what I used at work.  But I'd love
to get a more general generative naming language in there that could
support hierarchy as Roy describes.

Mark.
--
Mark Baker.   Ottawa, Ontario, CANADA.        http://www.markbaker.ca

> But I'd love
> to get a more general generative naming language in there that could
> support hierarchy as Roy describes.

Well, let's start building one.

Strawman01
<!-- provide the URI pattern to use -->
<form resource="http://example.com/quotes/${exchange}/${symbol}"
method='get'>
  <input name='exchange' type='text' />
  <input name='symbol' type='text'  />
</form>

Strawman02
<!-- provide the URI pattern to use, plus a 'class' attribute to indicate
the meaning of the input data - this allows a spider to discover all the
services which accept some form of data (like US zip code, telephone number,
etc) -->
<form resource="http://example.com/quotes/${exchange}/${symbol}"
method='get'>
  <input name='exchange' type='text' class='stock.exchange' />
  <input name='symbol' type='text' class='security.symbol' />
</form>

I've been looking at how map an xml tree into the path and same depth
params into the forms, ala
<Music><Artist><Name>ThieveryCorp</Name><Rating>5</Rating></Artist></Mus
ic>

gets mapped into something like GET /Music/Artist?Name=ThieveryCorp and
GET /Music/Artist/Rating?Name=ThieveryCorp

Mixed ns are a pain, but if you adopt the convention that the ns decls
are somehow in the algorithm, then it gets a little bit more managable.

Cheers,
Dave

> -----Original Message-----
> From: Mark Baker [mailto:distobj@...]
> Sent: Tuesday, June 01, 2004 8:38 PM
> To: David Orchard
> Cc: rest-discuss@yahoogroups.com
> Subject: Re: [rest-discuss] Re-using information fields for queries in
> REST
>
>
> On Tue, Jun 01, 2004 at 05:47:54PM -0700, David Orchard wrote:
> > Gotcha on the use of hierarchy rather than flat where appropriate.
> >
> > > -----Original Message-----
> > > From: Roy T. Fielding [mailto:fielding@...]
> >
> > <snip/>
> > > Anyway, we are talking about resource discovery over arbitrary
> > > data categories, and hence non-hierarchical in nature.  There is
> > > nothing wrong with telling the client how it can form URI's,
> > > assuming that such a function doesn't change much over time.
> > > Again, for cache reasons, I prefer methods of telling the client
> > > to use the template
> > >
> > >     http://example.com/quotes/${exchange}/${symbol}
> > >
> > > rather than the template
> > >
> > >     http://example.com/quotes?market=${exchange}&symbol=${symbol}
> > >
> > > There is nothing stopping WSDL-like technology from defining
> > > both of these mechanisms.
> > >
> > > ....Roy
> > >
> >
> > Hey, now there's an idea.  Maybe even official WSDL technology...
>
> *groan*  Ok, sure, *now* you support my "make WSDL more form-like"
> suggestions. 8-)
>
> The new HTTP binding goes further in this direction, but still falls
> short largely because it bumps up against the *very* different demands
> of a forms language compared with an interface description language.
>
> I'd personally prefer to start over with a forms language, which is
> why I created RDF Forms; http://www.markbaker.ca/2003/05/RDF-Forms/ .
> But it has a bit of legacy in its support of www-form-urlencoded
> serializations for POST bodies and URIs largely because that's what
> server APIs easily support and it's what I used at work.  But I'd love
> to get a more general generative naming language in there that could
> support hierarchy as Roy describes.
>
> Mark.
> --
> Mark Baker.   Ottawa, Ontario, CANADA.        http://www.markbaker.ca

This sounds very relevant to how XForms could use GET.

I am assuming that we want the stronger constraint of
bookmarkability, right?  Not just caching?

So that we are not talking about GET with a request body (which could
perhaps be made cachable, e.g., using "Vary") but a means of mapping
an XML document (which could be just a property set for flat vs
hierarchical addressing) into a URI.

E.g., a "application/iriencoded-xml" MIME type.

-bryan

--- In rest-discuss@yahoogroups.com, "David Orchard" <orchard@p...>
wrote:
> I've been looking at how map an xml tree into the path and same
depth
> params into the forms, ala
>
<Music><Artist><Name>ThieveryCorp</Name><Rating>5</Rating></Artist></M
us
> ic>
>
> gets mapped into something like GET /Music/Artist?Name=ThieveryCorp
and
> GET /Music/Artist/Rating?Name=ThieveryCorp
>
> Mixed ns are a pain, but if you adopt the convention that the ns
decls
> are somehow in the algorithm, then it gets a little bit more
managable.
>
> Cheers,
> Dave
>
> > -----Original Message-----
> > From: Mark Baker [mailto:distobj@a...]
> > Sent: Tuesday, June 01, 2004 8:38 PM
> > To: David Orchard
> > Cc: rest-discuss@yahoogroups.com
> > Subject: Re: [rest-discuss] Re-using information fields for
queries in
> > REST
> >
> >
> > On Tue, Jun 01, 2004 at 05:47:54PM -0700, David Orchard wrote:
> > > Gotcha on the use of hierarchy rather than flat where
appropriate.
> > >
> > > > -----Original Message-----
> > > > From: Roy T. Fielding [mailto:fielding@g...]
> > >
> > > <snip/>
> > > > Anyway, we are talking about resource discovery over arbitrary
> > > > data categories, and hence non-hierarchical in nature.  There
is
> > > > nothing wrong with telling the client how it can form URI's,
> > > > assuming that such a function doesn't change much over time.
> > > > Again, for cache reasons, I prefer methods of telling the
client
> > > > to use the template
> > > >
> > > >     http://example.com/quotes/${exchange}/${symbol}
> > > >
> > > > rather than the template
> > > >
> > > >     http://example.com/quotes?market=${exchange}
&symbol=${symbol}
> > > >
> > > > There is nothing stopping WSDL-like technology from defining
> > > > both of these mechanisms.
> > > >
> > > > ....Roy
> > > >
> > >
> > > Hey, now there's an idea.  Maybe even official WSDL
technology...
> >
> > *groan*  Ok, sure, *now* you support my "make WSDL more form-like"
> > suggestions. 8-)
> >
> > The new HTTP binding goes further in this direction, but still
falls
> > short largely because it bumps up against the *very* different
demands
> > of a forms language compared with an interface description
language.
> >
> > I'd personally prefer to start over with a forms language, which
is
> > why I created RDF Forms; http://www.markbaker.ca/2003/05/RDF-
Forms/ .
> > But it has a bit of legacy in its support of www-form-urlencoded
> > serializations for POST bodies and URIs largely because that's
what
> > server APIs easily support and it's what I used at work.  But I'd
love
> > to get a more general generative naming language in there that
could
> > support hierarchy as Roy describes.
> >
> > Mark.
> > --
> > Mark Baker.   Ottawa, Ontario, CANADA.
http://www.markbaker.ca

In the category of "never post before coffee", forget my remarks
about caching GET with a request entity.

However, I am interested in the relevance of this discussion to
XForms and GET.

-bryan

--- In rest-discuss@yahoogroups.com, "thompsonbry" <thompsonbry@s...>
wrote:
> This sounds very relevant to how XForms could use GET.
>
> I am assuming that we want the stronger constraint of
> bookmarkability, right?  Not just caching?
>
> So that we are not talking about GET with a request body (which
could
> perhaps be made cachable, e.g., using "Vary") but a means of
mapping
> an XML document (which could be just a property set for flat vs
> hierarchical addressing) into a URI.
>
> E.g., a "application/iriencoded-xml" MIME type.
>
> -bryan
>
> --- In rest-discuss@yahoogroups.com, "David Orchard" <orchard@p...>
> wrote:
> > I've been looking at how map an xml tree into the path and same
> depth
> > params into the forms, ala
> >
>
<Music><Artist><Name>ThieveryCorp</Name><Rating>5</Rating></Artist></M
> us
> > ic>
> >
> > gets mapped into something like GET /Music/Artist?
Name=ThieveryCorp
> and
> > GET /Music/Artist/Rating?Name=ThieveryCorp
> >
> > Mixed ns are a pain, but if you adopt the convention that the ns
> decls
> > are somehow in the algorithm, then it gets a little bit more
> managable.
> >
> > Cheers,
> > Dave
> >
> > > -----Original Message-----
> > > From: Mark Baker [mailto:distobj@a...]
> > > Sent: Tuesday, June 01, 2004 8:38 PM
> > > To: David Orchard
> > > Cc: rest-discuss@yahoogroups.com
> > > Subject: Re: [rest-discuss] Re-using information fields for
> queries in
> > > REST
> > >
> > >
> > > On Tue, Jun 01, 2004 at 05:47:54PM -0700, David Orchard wrote:
> > > > Gotcha on the use of hierarchy rather than flat where
> appropriate.
> > > >
> > > > > -----Original Message-----
> > > > > From: Roy T. Fielding [mailto:fielding@g...]
> > > >
> > > > <snip/>
> > > > > Anyway, we are talking about resource discovery over
arbitrary
> > > > > data categories, and hence non-hierarchical in nature.
There
> is
> > > > > nothing wrong with telling the client how it can form URI's,
> > > > > assuming that such a function doesn't change much over time.
> > > > > Again, for cache reasons, I prefer methods of telling the
> client
> > > > > to use the template
> > > > >
> > > > >     http://example.com/quotes/${exchange}/${symbol}
> > > > >
> > > > > rather than the template
> > > > >
> > > > >     http://example.com/quotes?market=${exchange}
> &symbol=${symbol}
> > > > >
> > > > > There is nothing stopping WSDL-like technology from defining
> > > > > both of these mechanisms.
> > > > >
> > > > > ....Roy
> > > > >
> > > >
> > > > Hey, now there's an idea.  Maybe even official WSDL
> technology...
> > >
> > > *groan*  Ok, sure, *now* you support my "make WSDL more form-
like"
> > > suggestions. 8-)
> > >
> > > The new HTTP binding goes further in this direction, but still
> falls
> > > short largely because it bumps up against the *very* different
> demands
> > > of a forms language compared with an interface description
> language.
> > >
> > > I'd personally prefer to start over with a forms language,
which
> is
> > > why I created RDF Forms; http://www.markbaker.ca/2003/05/RDF-
> Forms/ .
> > > But it has a bit of legacy in its support of www-form-urlencoded
> > > serializations for POST bodies and URIs largely because that's
> what
> > > server APIs easily support and it's what I used at work.  But
I'd
> love
> > > to get a more general generative naming language in there that
> could
> > > support hierarchy as Roy describes.
> > >
> > > Mark.
> > > --
> > > Mark Baker.   Ottawa, Ontario, CANADA.
> http://www.markbaker.ca

-----Original Message-----
From: thompsonbry [mailto:thompsonbry@...]
Sent: Wednesday, June 02, 2004 4:51 AM
To: rest-discuss@yahoogroups.com
Subject: [rest-discuss] Re: Re-using information fields for queries in REST

This sounds very relevant to how XForms could use GET.

I am assuming that we want the stronger constraint of
bookmarkability, right?  Not just caching?

So that we are not talking about GET with a request body (which could
perhaps be made cachable, e.g., using "Vary") but a means of mapping
an XML document (which could be just a property set for flat vs
hierarchical addressing) into a URI.

E.g., a "application/iriencoded-xml" MIME type.

-bryan

--- In rest-discuss@yahoogroups.com, "David Orchard" <orchard@p...>
wrote:
> I've been looking at how map an xml tree into the path and same
depth
> params into the forms, ala
>
<Music><Artist><Name>ThieveryCorp</Name><Rating>5</Rating></Artist></M
us
> ic>
>
> gets mapped into something like GET /Music/Artist?Name=ThieveryCorp
and
> GET /Music/Artist/Rating?Name=ThieveryCorp
>
> Mixed ns are a pain, but if you adopt the convention that the ns
decls
> are somehow in the algorithm, then it gets a little bit more
managable.
>
> Cheers,
> Dave
>
> > -----Original Message-----
> > From: Mark Baker [mailto:distobj@a...]
> > Sent: Tuesday, June 01, 2004 8:38 PM
> > To: David Orchard
> > Cc: rest-discuss@yahoogroups.com
> > Subject: Re: [rest-discuss] Re-using information fields for
queries in
> > REST
> >
> >
> > On Tue, Jun 01, 2004 at 05:47:54PM -0700, David Orchard wrote:
> > > Gotcha on the use of hierarchy rather than flat where
appropriate.
> > >
> > > > -----Original Message-----
> > > > From: Roy T. Fielding [mailto:fielding@g...]
> > >
> > > <snip/>
> > > > Anyway, we are talking about resource discovery over arbitrary
> > > > data categories, and hence non-hierarchical in nature.  There
is
> > > > nothing wrong with telling the client how it can form URI's,
> > > > assuming that such a function doesn't change much over time.
> > > > Again, for cache reasons, I prefer methods of telling the
client
> > > > to use the template
> > > >
> > > >     http://example.com/quotes/${exchange}/${symbol}
> > > >
> > > > rather than the template
> > > >
> > > >     http://example.com/quotes?market=${exchange}
&symbol=${symbol}
> > > >
> > > > There is nothing stopping WSDL-like technology from defining
> > > > both of these mechanisms.
> > > >
> > > > ....Roy
> > > >
> > >
> > > Hey, now there's an idea.  Maybe even official WSDL
technology...
> >
> > *groan*  Ok, sure, *now* you support my "make WSDL more form-like"
> > suggestions. 8-)
> >
> > The new HTTP binding goes further in this direction, but still
falls
> > short largely because it bumps up against the *very* different
demands
> > of a forms language compared with an interface description
language.
> >
> > I'd personally prefer to start over with a forms language, which
is
> > why I created RDF Forms; http://www.markbaker.ca/2003/05/RDF-
Forms/ .
> > But it has a bit of legacy in its support of www-form-urlencoded
> > serializations for POST bodies and URIs largely because that's
what
> > server APIs easily support and it's what I used at work.  But I'd
love
> > to get a more general generative naming language in there that
could
> > support hierarchy as Roy describes.
> >
> > Mark.
> > --
> > Mark Baker.   Ottawa, Ontario, CANADA.       
http://www.markbaker.ca

I was further thinking about modeling of identifiers in xml versus URIs and the
use of them in relation to other fields for queries.  It seems that any XML
identifier is problematic to algorithmically map to a URI.

My scenario: I have an Artist List structure containing Artist structures with a
Name and an uri reference, ie <ArtistList><Artist><Name>Thievery
Corp</Name><URI>http://www.eslmusic.com/artists/thievery.html</URI></Artist></Ar\
tistList>

I want to support getting the entire Artist information, or just a single field.
We earlier said that making the Artist identifier hierarchical is a Good Thing. 
This would look like:

GET /ArtistList/Artist/id/xyz.

But in my xml data structure, I specified that the Name structure uniquely
identifies the band in my database.  I end up having 2 primary keys: one if I
use URIs, and another if I were to do an XML based query.  If I used the Name as
the key, the URI looks more like

./Artist/Name/Thievery%20Corp

If I then want to get the value of the URI field where the Artist=Thievery Corp,
my query might look something like:

GET /ArtistList/Artist/Name/Thievery%20Corp/URI
or
GET /ArtistList/Artist/Name/Thievery%20Corp?field=URI

I prefer the former because the URI field is hierarchical within the Artist
structure, it's just that the darned Name messes up the hierarchy.  I don't want
to use client side identifiers, ie fragment ids such as Artist#ThieveryCorp or
even Artist/Name/Thievery%20Corp#thievery%20CorpURI

So I then thought in cases where the field being requested was at the same or
lower level than the identifier, I could use the path component to specify the
Artist, as in

GET /ArtistList/Artist;Name=Thievery%20Corp/URI

Which I'd interpret as for the Artist who's name field is thievery corp, get the
URI field.  I wonder if this is a good way of modelling the query?

I think you should now have the rough gist of the way that I'm thinking about
binding xml structures to URIs, and this has led to some questions:

1. What is the best design, or even the trade-offs to be made across designs,
when binding xml identifiers to URIs

2. How should requests for a "secondary resource" in a component be expressed
when the secondary resource is at the same level in the xml hierarchy as the xml
identifier.

I wasn't quite sure which way Roy was saying is the best way given the different
examples of http://example.com/quotes/${exchange}/${symbol} and 
/Artist/id/12345678.   That is, whether the URI for the resource is
parameterizable and thus generated by a client, or whether the identifier is
opaque and the client has to do a 2nd pass to get it.  It seems like there's an
important point about naming of resources, which is that maybe the xml way of
identifying resources doesn't work well with the Web.

Thanks again for all your time,
Dave

Hey,

On Wed, Jun 02, 2004 at 04:32:58PM -0700, David Orchard wrote:
> I was further thinking about modeling of identifiers in xml versus URIs and
the use of them in relation to other fields for queries.  It seems that any XML
identifier is problematic to algorithmically map to a URI.
>
> My scenario: I have an Artist List structure containing Artist structures with
a Name and an uri reference, ie <ArtistList><Artist><Name>Thievery
Corp</Name><URI>http://www.eslmusic.com/artists/thievery.html</URI></Artist></Ar\
tistList>
>
> I want to support getting the entire Artist information, or just a single
field.  We earlier said that making the Artist identifier hierarchical is a Good
Thing.  This would look like:
>
> GET /ArtistList/Artist/id/xyz.

I think that's the issue; I don't believe that it need look like that.
That, for a particular document, an Artist is encapsulated within an
ArtistList, doesn't dictate, I believe, that an Artist is hierarchically
related to an ArtistList.  Hierarchy captures relationships between
resources such as UML's aggregation by-value; that if the aggregator
dies, the aggregatee(?) dies too.  That doesn't hold for ArtistList; if
I remove an instance of a list containing an artist, the artist doesn't
go away.

So that URI above could be /Artist/id/xyz.  If you want to "query" by
name, try /Artist/name/Foo%20Bar, and then as Roy was suggesting,
redirect back to /Artist/id/xyz ... assuming there's only one known
"Foo Bar" band.  If not, return your ArtistList, and perhaps in that
list put the /Artist/id/??? URI for each artist.

Does that make sense?  It's a hard subject to explain.

Mark.
--
Mark Baker.   Ottawa, Ontario, CANADA.        http://www.markbaker.ca

Dave,

I searched on this a bit, but I could not find the gospel according
to the TAG.  However, it is my rememberance that URIs no longer have
practical length limits and that people should not design interfaces
as if they did.

So, why not just serialize the XML using the XML syntax in, e.g.,
UTF-8, and then escape any characters that need to be escaped for
the URI encoding?

I mean, we can probably do better than this, e.g., with a dictionary
of namespace URIs, element names and attribute names that would yield
a more compact representation of the XML instance data (all of which
reminds me of binary XML), but why bother?  Is't it good enough to do
this in the simplest manner possible so that we can move forward?

-bryan

--- In rest-discuss@yahoogroups.com, "David Orchard" <orchard@p...>
wrote:
> I think one of the hardest parts of coming up with a "uriencoded-
xml" format is dealing with those pesky QNames.  I wrote a while ago
about this
http://www.pacificspirit.com/blog/2004/04/29/binding_qnames_to_uris.
>
> I've almost gotten to the point of thinking that it's just simply
to awful to binding lexical QNames or NS decls to URIs for binding
potentially many qnames to URIs.  The approach of specifying that the
ns decl is part of the "algorithm" allows for I think a pretty common
case, the authority creating the resources can specify the ns name
decls ahead of time.  In this case, the creator of the Author
resources not surprisingly owns the Author namespace names.  A prefix
is not required for the default namespace, and a prefix is required
for using ns decls outside the default ns.
>
> There is a big downside in that the xml fragments are no-longer
self-describing as they are missing their ns decls in-line.  If
somebody changes the namespace name but not the ns prefix, things
could get pretty hairy.  And distributed extensibility wouldn't be
supported as a client that knew about a davens:extension that was
unknown to the service wouldn't be able to send the extension they
know about but wasn't in the algorithm.  I suppose it could be
possible to say that extensions can be sent in ugly lexical form as
that is the "hard but possible" case in the "make simple things
simple and hard things possible" algorithm.
>
> In retrospect, I'm becoming convinced that marrying XML sans
namespace tree structures to the URI tree and query structure works
fine, but marrying XML namespaced tree structures to URIs has been
almost useless by the decision to make ns names absolute URIs.  In
order to map some kind of xml to URIs, we have to adopt some kind of
constraints, like "ns decls are implicit", to make it usable.  One
thing I am curious about is whether people see much need for mapping
mixed ns xml into URIs, or if most of the scenarios involved single
ns..
>
> Cheers,
> Dave
>
> -----Original Message-----
> From: thompsonbry [mailto:thompsonbry@s...]
> Sent: Wednesday, June 02, 2004 4:51 AM
> To: rest-discuss@yahoogroups.com
> Subject: [rest-discuss] Re: Re-using information fields for queries
in REST
>
>
> This sounds very relevant to how XForms could use GET.
>
> I am assuming that we want the stronger constraint of
> bookmarkability, right?  Not just caching?
>
> So that we are not talking about GET with a request body (which
could
> perhaps be made cachable, e.g., using "Vary") but a means of
mapping
> an XML document (which could be just a property set for flat vs
> hierarchical addressing) into a URI.
>
> E.g., a "application/iriencoded-xml" MIME type.
>
> -bryan
>
> --- In rest-discuss@yahoogroups.com, "David Orchard" <orchard@p...>
> wrote:
> > I've been looking at how map an xml tree into the path and same
> depth
> > params into the forms, ala
> >
>
<Music><Artist><Name>ThieveryCorp</Name><Rating>5</Rating></Artist></M
> us
> > ic>
> >
> > gets mapped into something like GET /Music/Artist?
Name=ThieveryCorp
> and
> > GET /Music/Artist/Rating?Name=ThieveryCorp
> >
> > Mixed ns are a pain, but if you adopt the convention that the ns
> decls
> > are somehow in the algorithm, then it gets a little bit more
> managable.
> >
> > Cheers,
> > Dave
> >
> > > -----Original Message-----
> > > From: Mark Baker [mailto:distobj@a...]
> > > Sent: Tuesday, June 01, 2004 8:38 PM
> > > To: David Orchard
> > > Cc: rest-discuss@yahoogroups.com
> > > Subject: Re: [rest-discuss] Re-using information fields for
> queries in
> > > REST
> > >
> > >
> > > On Tue, Jun 01, 2004 at 05:47:54PM -0700, David Orchard wrote:
> > > > Gotcha on the use of hierarchy rather than flat where
> appropriate.
> > > >
> > > > > -----Original Message-----
> > > > > From: Roy T. Fielding [mailto:fielding@g...]
> > > >
> > > > <snip/>
> > > > > Anyway, we are talking about resource discovery over
arbitrary
> > > > > data categories, and hence non-hierarchical in nature.
There
> is
> > > > > nothing wrong with telling the client how it can form URI's,
> > > > > assuming that such a function doesn't change much over time.
> > > > > Again, for cache reasons, I prefer methods of telling the
> client
> > > > > to use the template
> > > > >
> > > > >     http://example.com/quotes/${exchange}/${symbol}
> > > > >
> > > > > rather than the template
> > > > >
> > > > >     http://example.com/quotes?market=${exchange}
> &symbol=${symbol}
> > > > >
> > > > > There is nothing stopping WSDL-like technology from defining
> > > > > both of these mechanisms.
> > > > >
> > > > > ....Roy
> > > > >
> > > >
> > > > Hey, now there's an idea.  Maybe even official WSDL
> technology...
> > >
> > > *groan*  Ok, sure, *now* you support my "make WSDL more form-
like"
> > > suggestions. 8-)
> > >
> > > The new HTTP binding goes further in this direction, but still
> falls
> > > short largely because it bumps up against the *very* different
> demands
> > > of a forms language compared with an interface description
> language.
> > >
> > > I'd personally prefer to start over with a forms language,
which
> is
> > > why I created RDF Forms; http://www.markbaker.ca/2003/05/RDF-
> Forms/ .
> > > But it has a bit of legacy in its support of www-form-urlencoded
> > > serializations for POST bodies and URIs largely because that's
> what
> > > server APIs easily support and it's what I used at work.  But
I'd
> love
> > > to get a more general generative naming language in there that
> could
> > > support hierarchy as Roy describes.
> > >
> > > Mark.
> > > --
> > > Mark Baker.   Ottawa, Ontario, CANADA.
> http://www.markbaker.ca
>
>
>
> Yahoo! Groups Sponsor
>
> ADVERTISEMENT
>
<http://rd.yahoo.com/SIG=129ga231f/M=295196.4901138.6071305.3001176/D=
groups/S=1705701014:HM/EXP=1086263534/A=2128215/R=0/SIG=10se96mf6/*htt
p://companion.yahoo.com> click here
>   <http://us.adserver.yahoo.com/l?
M=295196.4901138.6071305.3001176/D=groups/S=:HM/A=2128215/rand=2945531
86>
>
>
>   _____
>
> Yahoo! Groups Links
>
>
> * To visit your group on the web, go to:
> http://groups.yahoo.com/group/rest-discuss/
>
>
> * To unsubscribe from this group, send an email to:
> rest-discuss-unsubscribe@yahoogroups.com <mailto:rest-discuss-
unsubscribe@yahoogroups.com?subject=Unsubscribe>
>
>
> * Your use of Yahoo! Groups is subject to the Yahoo! Terms of
Service <http://docs.yahoo.com/info/terms/> .

--- In rest-discuss@yahoogroups.com, "thompsonbry" <thompsonbry@s...>
wrote:
> I'm looking at an integration of Chiba's XForms implementation into
a
> REST repository.  Does anyone have experience with integrating
> Chiba?  (One of the chiba authors suggested the 1060 folks had done
> this, which is why I'm posting to this list.)
>
> Thanks,
>
> -bryan

The latest version of Chiba XForms we integrated was 0.9.5. This is
available in the latest NetKernel Standard Edition download.

The basics of what we did was to abstract three things away from the
Chiba engine:
1) servlet dependence
2) XSLT stylesheet (xforms xml -> HTML ) dependence
3) session state
We did this so that the XForms engine became stateless and more
flexible.

I know that we had to make some patches to the source to acheive what
we needed. It wasn't me that did the work but I can pass on the
details of a collegue that did if you want to discuss.

Tony Butterfield
www.1060.org

--- David Orchard <orchard@...> wrote:
> It seems that any XML identifier is problematic to algorithmically
> map to a URI.

Yes. As you've noticed, this is impossible with just simple
directory-style slashes.

But can I suggest that you step back and ask what problem you're
trying to solve?

If your problem is "I have settled on XML, the documents will be
entirely freeform, and I want a uniform way of identifying any random
node so I can stuff them into URIs" then I guess you want XPath or
XPointer. Check them out. The expressions are very complex though.

However, if that *isn't* your problem, then perhaps you should think
about the URI interface first.  It seems to me that you really just
want:

http://host/artist/Thievery%20Corporation
http://host/artist/Thievery%20Corporation/bio
http://host/artist/Thievery%20Corporation/genre
http://host/artist/Thievery%20Corporation/website

You may protest that you have to write different get/set methods for
each one of those URIs! And what if your underlying data structure
changes?

However, some would say this is the beauty of REST. It forces you to
think about the consumers of your interfaces. Hiding the details is
good. This means you can change your underlying data structure at
will.


=====
--
Neil Kandalgaonkar
neil_j_k@...

On Fri, 4 Jun 2004, Neil Kandalgaonkar wrote:
> If your problem is "I have settled on XML, the documents will be
> entirely freeform, and I want a uniform way of identifying any random
> node so I can stuff them into URIs" then I guess you want XPath or
> XPointer. Check them out. The expressions are very complex though.
>
> However, if that *isn't* your problem, then perhaps you should think
> about the URI interface first.  It seems to me that you really just
> want:
>
> http://host/artist/Thievery%20Corporation
> http://host/artist/Thievery%20Corporation/bio
> http://host/artist/Thievery%20Corporation/genre
> http://host/artist/Thievery%20Corporation/website

A really elegant way of cleaning up the confusion, Neil.

In my own API, that is the approach I took.  The important thing is that
incoming data structures do not map directly to internal data structures.
The requester only sees the data structures at the application level, so
requests say something like "here is the order of a set of songs", as
opposed to "here are the sequence numbers of song URLs in the set with id
#N.

- Lucas

I am looking to choose an XML representation of an HTTP requests and
responses as part of a REST workflow system.  The representation will
be used in at least two ways: 1) as templates of requests that are
used to delegate an activity selected by some precondition -- the
actual request might be generated by some XML processing chain based
on that template and visible workflow state; and 2) as journels of
the request and the response intended to provide inspectable state
as a workflow evolves.

E.g.,

<http>
   <request method="..." requestURL="..." version="HTTP/1.1">
      <header name="host">...</header>
      ...
      <entity xlink:href="..." xlink:type="resource|locator">
      ...
      </entity>
   </request>
   <response statusCode="..." reasonLine="..." version="HTTP/1.1">
      <header name="Content-Type">...</header>
      ...
      <entity xlink:href="..." xlink:type="resource|locator">
      ...
      </entity>
   </response>
</http>

The notion is that the request/response entity is optional (since
it is not always present) and that it may either be represented
inline or as a link to a resource whose representation is that
entity.  In particular, this seems to be a better way to store
a transaction journel or record the evolving state of requests
and responses on some evolving workflow state.

This sort of thing is relatively straightforward, but it seems like
it could be useful in a lot of places, e.g., a transaction log for
a REST repository, so I was wondering if there has been any effort
to develop such an XML vocabulary and whether or not it might
generalize out of the specific use case for which it was developed.

Thanks,

-bryan

It's not XML, but if it's HTTP modelling you want, you might be
interested in;

http://www.w3.org/Architecture/state

An XML serialization of such a model would be trivial, of course.

Mark.

Hi David,

Here is my two cents.
If the following speel does not directly address the issues that concern you
then consider this as some ideas that I am airing using your problem as an
example.

I think there are a couple of issues here and it may help to separate them.

1. For any particular artist you want to retrieve:
       - name
       - eye color
       - style
       - web site
       - everything (ie. all of the above)

    This is a set of information that you wish to be able to address
    individually or collectively.

2. You want to run queries on the set of artists:
       - artists with green eyes
       - rap singers

3. You want to have arbitraty lists of artists:
       - artists I like
       - artists currently on tour

OK, so that's not what you want but it will do to demonstrate the following
points.

a) It doesn't matter how you reference your artists as the url is opaque.
    Consequently you can keep it simple.
         GET /artist/LisaSimpson

    The URI could be /artist/12345678. The ONLY difference between this and
    /artist/LisaSimpson is that the latter is easier for a human to remember.

    This might return some xml like this:

     <artist>
         <name      id="/artist/LisaSimpson/name">Lisa Simpson</name>
         <eye-color id="./eye-color">Green</eye-color>
         <style     id="LisaSimpson/style">Blues</style>
         <web-site  id="./web-site"
href="http://www.thesimpsons.com/lisa-simpson" />
     </artist>

    I have mixed various forms of relative URI for demonstration purposes.
Which one
    you use doesn't really matter but you would probably choose one and stick
with it.

b)  Each property within the artist record has its own relative URI which
you can dereference.
     This means that the User Agent does not manufacture URIs. They are
always provided by
     the Origin Server.

     The relative URI id="./eye-color"" resolves to:
          GET /artist/LisaSimpson/eye-color

     This might return the following xml:

     <eye-color artist="..">Blue</eye-color>

     Note that it is possible to get back to the artist from here. I'm not
suggesting that you
     have to do that, just pointing out that it is possible.

c)  The entry can be created using a HTTP POST to the artist uri.

       POST /artist

       <artist>
           <name>Bart Simpson</name>
           <eye-color>Blue</eye-color>
           <style>Rap</style>
           <web-site>http://www.thesimpsons.com/bart-simpson</web-site>
       </artist>

     The same could be done using HTML form encoding.

     The artist can be deleted like this.

     DELETE /artist/BartSimpson

d)  You can query on existing attributes of the artist.

     GET /artist?eye-color=Blue

     <artistlist>
         <artistref href="/artist/LisaSimpson">Lisa Simpson</artistref>
         <artistref href="/artist/Madonna">Madonna</artistref>
     </artistlist>

     GET /artist?name=Lisa%20Simpson

     <artistlist>
         <artistref href="/artist/LisaSimpson">Lisa Simpson</artistref>
     </artistlist>

     These queries can be generated by an HTML Form. The query part
     of a URL is not opaque to the User Agent. The client is expected
     to provide query parameters for use in searches.

     Note that the http path, before the query, is still opaque.
     It could be /artist or /search or /cgi-bin/artistquery.cgi.
     However, I believe that the prefered restful practice is to direct
     the query to the collection URL, /artist in this case, and map this
     to the search utility, typically by an entry in the htaccess file.

e)  You can have arbitrary lists of artists.

     GET /artistlists/my-favorites

     <artistlist title="My favorite artists">
         <artistref id="./LisaSimpson" href="/artist/LisaSimpson">Lisa
Simpson</artistref>
         <artistref id="./BartSimpson" href="/artist/BartSimpson">Bart
Simpson</artistref>
     </artistlist>

     Note that each item in the list has its own URI.

     An entry in this list can be deleted like this:

     DELETE /artistlists/my-favorites/BartSimpson

     An entry can be added to this list like this:

     POST /artistlists/my-favorites

     <artistref href"/artist/BartSimpson">Bart Simpson</artistref>


Points of note
--------------

1.  URIs are always generated by the origin server.

2.  The client only calculates a URI in two circumstances:
      a) it converts relative URIs, generated by the origin server,
         into absolute URIs
      b) it may add query parameters to the end of a search
         URI provided by the origin server.

3.  All xml elements that can be addressed individually are provided
     with a relative URI by the origin server.

I think this approach is restful, but I have thought that before and been
wrong.
I have not seen it suggested before, however, I have not trolled the archive
so I
cannot be certain.

Although I have not attempted it, it should be possible to process all the
xml above into HTML using a suitable transform or style sheet.

I hope you find this interesting and maybe even helpful.
Regards
Donald.

> -----Original Message-----
> From: David Orchard [mailto:orchard@...]
> Sent: Thursday, 3 June 2004 9:33 AM
> To: rest-discuss@yahoogroups.com
> Subject: [rest-discuss] Identifiers: higher precedence than other
> fields?
>
>
> I was further thinking about modeling of identifiers in xml
> versus URIs and the use of them in relation to other fields for
> queries.  It seems that any XML identifier is problematic to
> algorithmically map to a URI.
>
> My scenario: I have an Artist List structure containing Artist
> structures with a Name and an uri reference, ie
> <ArtistList><Artist><Name>Thievery
> Corp</Name><URI>http://www.eslmusic.com/artists/thievery.html</URI
> ></Artist></ArtistList>
>
> I want to support getting the entire Artist information, or just
> a single field.  We earlier said that making the Artist
> identifier hierarchical is a Good Thing.  This would look like:
>
> GET /ArtistList/Artist/id/xyz.
>
> But in my xml data structure, I specified that the Name structure
> uniquely identifies the band in my database.  I end up having 2
> primary keys: one if I use URIs, and another if I were to do an
> XML based query.  If I used the Name as the key, the URI looks more like
>
> ./Artist/Name/Thievery%20Corp
>
> If I then want to get the value of the URI field where the
> Artist=Thievery Corp, my query might look something like:
>
> GET /ArtistList/Artist/Name/Thievery%20Corp/URI
> or
> GET /ArtistList/Artist/Name/Thievery%20Corp?field=URI
>
> I prefer the former because the URI field is hierarchical within
> the Artist structure, it's just that the darned Name messes up
> the hierarchy.  I don't want to use client side identifiers, ie
> fragment ids such as Artist#ThieveryCorp or even
> Artist/Name/Thievery%20Corp#thievery%20CorpURI
>
> So I then thought in cases where the field being requested was at
> the same or lower level than the identifier, I could use the path
> component to specify the Artist, as in
>
> GET /ArtistList/Artist;Name=Thievery%20Corp/URI
>
> Which I'd interpret as for the Artist who's name field is
> thievery corp, get the URI field.  I wonder if this is a good way
> of modelling the query?
>
> I think you should now have the rough gist of the way that I'm
> thinking about binding xml structures to URIs, and this has led
> to some questions:
>
> 1. What is the best design, or even the trade-offs to be made
> across designs, when binding xml identifiers to URIs
>
> 2. How should requests for a "secondary resource" in a component
> be expressed when the secondary resource is at the same level in
> the xml hierarchy as the xml identifier.
>
> I wasn't quite sure which way Roy was saying is the best way
> given the different examples of
http://example.com/quotes/${exchange}/${symbol} and  /Artist/id/12345678.
That is, whether the URI for the resource is parameterizable and thus
generated by a client, or whether the identifier is opaque and the client
has to do a 2nd pass to get it.  It seems like there's an important point
about naming of resources, which is that maybe the xml way of identifying
resources doesn't work well with the Web.

Thanks again for all your time,
Dave

This comes up now and again. I remember somebody really bright doing this a
few years ago.
Have you looked at these:
http://www.openhealth.org/documents/xmtp.htm
http://www.biglist.com/lists/xsl-list/archives/200001/msg00237.html


----- Original Message -----
From: "thompsonbry" <thompsonbry@...>
To: <rest-discuss@yahoogroups.com>
Sent: Saturday, June 05, 2004 6:39 AM
Subject: [rest-discuss] XML Representation of HTTP Requests and Responses?


> I am looking to choose an XML representation of an HTTP requests and
> responses as part of a REST workflow system.  The representation will
> be used in at least two ways: 1) as templates of requests that are
> used to delegate an activity selected by some precondition -- the
> actual request might be generated by some XML processing chain based
> on that template and visible workflow state; and 2) as journels of
> the request and the response intended to provide inspectable state
> as a workflow evolves.
>
> E.g.,
>
> <http>
>   <request method="..." requestURL="..." version="HTTP/1.1">
>      <header name="host">...</header>
>      ...
>      <entity xlink:href="..." xlink:type="resource|locator">
>      ...
>      </entity>
>   </request>
>   <response statusCode="..." reasonLine="..." version="HTTP/1.1">
>      <header name="Content-Type">...</header>
>      ...
>      <entity xlink:href="..." xlink:type="resource|locator">
>      ...
>      </entity>
>   </response>
> </http>
>
> The notion is that the request/response entity is optional (since
> it is not always present) and that it may either be represented
> inline or as a link to a resource whose representation is that
> entity.  In particular, this seems to be a better way to store
> a transaction journel or record the evolving state of requests
> and responses on some evolving workflow state.
>
> This sort of thing is relatively straightforward, but it seems like
> it could be useful in a lot of places, e.g., a transaction log for
> a REST repository, so I was wondering if there has been any effort
> to develop such an XML vocabulary and whether or not it might
> generalize out of the specific use case for which it was developed.
>
> Thanks,
>
> -bryan
>
>
>
>
>
> Yahoo! Groups Links
>
>
>
>
>
>

> The URI could be /artist/12345678. The ONLY difference between this and
>  /artist/LisaSimpson is that the latter is easier for a human to remember.
Not true - the other difference is that /artist/LisaSimpson could be
constructed from external information (like a telephone book or content from
some other resource) and a suitable description of the resources supported
by that service. It has to do with using internal identifiers .vs.
reasonably shareable identifiers (a zip code, proper name, etc).

----- Original Message -----
From: "Donald Strong" <dstrong@...>
To: "rest-discuss" <rest-discuss@yahoogroups.com>
Sent: Monday, June 07, 2004 9:21 PM
Subject: Re: [rest-discuss] Identifiers: higher precedence than other
fields?


>
> Hi David,
>
> Here is my two cents.
> If the following speel does not directly address the issues that concern
you
> then consider this as some ideas that I am airing using your problem as an
> example.
>
> I think there are a couple of issues here and it may help to separate
them.
>
> 1. For any particular artist you want to retrieve:
>       - name
>       - eye color
>       - style
>       - web site
>       - everything (ie. all of the above)
>
>    This is a set of information that you wish to be able to address
>    individually or collectively.
>
> 2. You want to run queries on the set of artists:
>       - artists with green eyes
>       - rap singers
>
> 3. You want to have arbitraty lists of artists:
>       - artists I like
>       - artists currently on tour
>
> OK, so that's not what you want but it will do to demonstrate the
following
> points.
>
> a) It doesn't matter how you reference your artists as the url is opaque.
>    Consequently you can keep it simple.
>         GET /artist/LisaSimpson
>
>    The URI could be /artist/12345678. The ONLY difference between this and
>    /artist/LisaSimpson is that the latter is easier for a human to
remember.
>
>    This might return some xml like this:
>
>     <artist>
>         <name      id="/artist/LisaSimpson/name">Lisa Simpson</name>
>         <eye-color id="./eye-color">Green</eye-color>
>         <style     id="LisaSimpson/style">Blues</style>
>         <web-site  id="./web-site"
> href="http://www.thesimpsons.com/lisa-simpson" />
>     </artist>
>
>    I have mixed various forms of relative URI for demonstration purposes.
> Which one
>    you use doesn't really matter but you would probably choose one and
stick
> with it.
>
> b)  Each property within the artist record has its own relative URI which
> you can dereference.
>     This means that the User Agent does not manufacture URIs. They are
> always provided by
>     the Origin Server.
>
>     The relative URI id="./eye-color"" resolves to:
>          GET /artist/LisaSimpson/eye-color
>
>     This might return the following xml:
>
>     <eye-color artist="..">Blue</eye-color>
>
>     Note that it is possible to get back to the artist from here. I'm not
> suggesting that you
>     have to do that, just pointing out that it is possible.
>
> c)  The entry can be created using a HTTP POST to the artist uri.
>
>       POST /artist
>
>       <artist>
>           <name>Bart Simpson</name>
>           <eye-color>Blue</eye-color>
>           <style>Rap</style>
>           <web-site>http://www.thesimpsons.com/bart-simpson</web-site>
>       </artist>
>
>     The same could be done using HTML form encoding.
>
>     The artist can be deleted like this.
>
>     DELETE /artist/BartSimpson
>
> d)  You can query on existing attributes of the artist.
>
>     GET /artist?eye-color=Blue
>
>     <artistlist>
>         <artistref href="/artist/LisaSimpson">Lisa Simpson</artistref>
>         <artistref href="/artist/Madonna">Madonna</artistref>
>     </artistlist>
>
>     GET /artist?name=Lisa%20Simpson
>
>     <artistlist>
>         <artistref href="/artist/LisaSimpson">Lisa Simpson</artistref>
>     </artistlist>
>
>     These queries can be generated by an HTML Form. The query part
>     of a URL is not opaque to the User Agent. The client is expected
>     to provide query parameters for use in searches.
>
>     Note that the http path, before the query, is still opaque.
>     It could be /artist or /search or /cgi-bin/artistquery.cgi.
>     However, I believe that the prefered restful practice is to direct
>     the query to the collection URL, /artist in this case, and map this
>     to the search utility, typically by an entry in the htaccess file.
>
> e)  You can have arbitrary lists of artists.
>
>     GET /artistlists/my-favorites
>
>     <artistlist title="My favorite artists">
>         <artistref id="./LisaSimpson" href="/artist/LisaSimpson">Lisa
> Simpson</artistref>
>         <artistref id="./BartSimpson" href="/artist/BartSimpson">Bart
> Simpson</artistref>
>     </artistlist>
>
>     Note that each item in the list has its own URI.
>
>     An entry in this list can be deleted like this:
>
>     DELETE /artistlists/my-favorites/BartSimpson
>
>     An entry can be added to this list like this:
>
>     POST /artistlists/my-favorites
>
>     <artistref href"/artist/BartSimpson">Bart Simpson</artistref>
>
>
> Points of note
> --------------
>
> 1.  URIs are always generated by the origin server.
>
> 2.  The client only calculates a URI in two circumstances:
>      a) it converts relative URIs, generated by the origin server,
>         into absolute URIs
>      b) it may add query parameters to the end of a search
>         URI provided by the origin server.
>
> 3.  All xml elements that can be addressed individually are provided
>     with a relative URI by the origin server.
>
> I think this approach is restful, but I have thought that before and been
> wrong.
> I have not seen it suggested before, however, I have not trolled the
archive
> so I
> cannot be certain.
>
> Although I have not attempted it, it should be possible to process all the
> xml above into HTML using a suitable transform or style sheet.
>
> I hope you find this interesting and maybe even helpful.
> Regards
> Donald.
>
> > -----Original Message-----
> > From: David Orchard [mailto:orchard@...]
> > Sent: Thursday, 3 June 2004 9:33 AM
> > To: rest-discuss@yahoogroups.com
> > Subject: [rest-discuss] Identifiers: higher precedence than other
> > fields?
> >
> >
> > I was further thinking about modeling of identifiers in xml
> > versus URIs and the use of them in relation to other fields for
> > queries.  It seems that any XML identifier is problematic to
> > algorithmically map to a URI.
> >
> > My scenario: I have an Artist List structure containing Artist
> > structures with a Name and an uri reference, ie
> > <ArtistList><Artist><Name>Thievery
> > Corp</Name><URI>http://www.eslmusic.com/artists/thievery.html</URI
> > ></Artist></ArtistList>
> >
> > I want to support getting the entire Artist information, or just
> > a single field.  We earlier said that making the Artist
> > identifier hierarchical is a Good Thing.  This would look like:
> >
> > GET /ArtistList/Artist/id/xyz.
> >
> > But in my xml data structure, I specified that the Name structure
> > uniquely identifies the band in my database.  I end up having 2
> > primary keys: one if I use URIs, and another if I were to do an
> > XML based query.  If I used the Name as the key, the URI looks more like
> >
> > ./Artist/Name/Thievery%20Corp
> >
> > If I then want to get the value of the URI field where the
> > Artist=Thievery Corp, my query might look something like:
> >
> > GET /ArtistList/Artist/Name/Thievery%20Corp/URI
> > or
> > GET /ArtistList/Artist/Name/Thievery%20Corp?field=URI
> >
> > I prefer the former because the URI field is hierarchical within
> > the Artist structure, it's just that the darned Name messes up
> > the hierarchy.  I don't want to use client side identifiers, ie
> > fragment ids such as Artist#ThieveryCorp or even
> > Artist/Name/Thievery%20Corp#thievery%20CorpURI
> >
> > So I then thought in cases where the field being requested was at
> > the same or lower level than the identifier, I could use the path
> > component to specify the Artist, as in
> >
> > GET /ArtistList/Artist;Name=Thievery%20Corp/URI
> >
> > Which I'd interpret as for the Artist who's name field is
> > thievery corp, get the URI field.  I wonder if this is a good way
> > of modelling the query?
> >
> > I think you should now have the rough gist of the way that I'm
> > thinking about binding xml structures to URIs, and this has led
> > to some questions:
> >
> > 1. What is the best design, or even the trade-offs to be made
> > across designs, when binding xml identifiers to URIs
> >
> > 2. How should requests for a "secondary resource" in a component
> > be expressed when the secondary resource is at the same level in
> > the xml hierarchy as the xml identifier.
> >
> > I wasn't quite sure which way Roy was saying is the best way
> > given the different examples of
> http://example.com/quotes/${exchange}/${symbol} and  /Artist/id/12345678.
> That is, whether the URI for the resource is parameterizable and thus
> generated by a client, or whether the identifier is opaque and the client
> has to do a 2nd pass to get it.  It seems like there's an important point
> about naming of resources, which is that maybe the xml way of identifying
> resources doesn't work well with the Web.
>
> Thanks again for all your time,
> Dave
>
>
>
>
>
> Yahoo! Groups Links
>
>
>
>
>
>

Hi Mike,
Thanks for replying.

> > The URI could be /artist/12345678. The ONLY difference between this and
> >  /artist/LisaSimpson is that the latter is easier for a human
> to remember.
> Not true - the other difference is that /artist/LisaSimpson could be
> constructed from external information (like a telephone book or
> content from
> some other resource) and a suitable description of the resources supported
> by that service. It has to do with using internal identifiers .vs.
> reasonably shareable identifiers (a zip code, proper name, etc).

What I was tring to say, in my clumsy way, is that the approach I was
describing
uses completely opaque paths that are always generated by the origin server.
There is no requirement for an User Agent to calculate the paths and
consequently
the origin server can use any naming convention it wants to.

The basis of my suggestion is that only internally generated identifiers are
used.
Obviously there are trade-offs with this approach. I am certainly not saying
that
it is the only way to go.

As far as using external sources for generating references to resources, as
you
describe above, the way I would do that is to query the system to determine
whether such an artist exists. So for example, the phone book lists a
"Lisa B Simpson" which could be used like this.

    GET /artist?name=Lisa%20B%20Simpson

The http path, /artist, suggests that only one artist should be returned,
however
the URI includes a query so some proxes will not cache the result.
Consequently,
the Origin Server may redirect to /artist/LisaSimpson which will be cached.
In this way aliases can be easily converted to the connonical URI for the
artist
(at least its connonical as far as the origin server is concerned).

Once again, you don't have to do it this way, but IMHO it simplifies the
logic
on the User Agent.

Regards
Donald.

Hi David,

Here is my two cents.
If the following speel does not directly address the issues that concern you
then consider this as some ideas that I am airing using your problem as an
example.

I think there are a couple of issues here and it may help to separate them.

1. For any particular artist you want to retrieve:
      - name
      - eye color
      - style
      - web site
      - everything (ie. all of the above)

   This is a set of information that you wish to be able to address
   individually or collectively.

2. You want to run queries on the set of artists:
      - artists with green eyes
      - rap singers

3. You want to have arbitraty lists of artists:
      - artists I like
      - artists currently on tour

OK, so that's not what you want but it will do to demonstrate the following
points.

a) It doesn't matter how you reference your artists as the url is opaque.
   Consequently you can keep it simple.
        GET /artist/LisaSimpson

   The URI could be /artist/12345678. The ONLY difference between this and
   /artist/LisaSimpson is that the latter is easier for a human to remember.

   This might return some xml like this:

    <artist>
        <name      id="/artist/LisaSimpson/name">Lisa Simpson</name>
        <eye-color id="./eye-color">Green</eye-color>
        <style     id="LisaSimpson/style">Blues</style>
        <web-site  id="./web-site"
href="http://www.thesimpsons.com/lisa-simpson" />
    </artist>

   I have mixed various forms of relative URI for demonstration purposes.
Which one
   you use doesn't really matter but you would probably choose one and stick
with it.

b)  Each property within the artist record has its own relative URI which
you can dereference.
    This means that the User Agent does not manufacture URIs. They are
always provided by
    the Origin Server.

    The relative URI id="./eye-color"" resolves to:
         GET /artist/LisaSimpson/eye-color

    This might return the following xml:

    <eye-color artist="..">Blue</eye-color>

    Note that it is possible to get back to the artist from here. I'm not
suggesting that you
    have to do that, just pointing out that it is possible.

c)  The entry can be created using a HTTP POST to the artist uri.

      POST /artist

      <artist>
          <name>Bart Simpson</name>
          <eye-color>Blue</eye-color>
          <style>Rap</style>
          <web-site>http://www.thesimpsons.com/bart-simpson</web-site>
      </artist>

    The same could be done using HTML form encoding.

    The artist can be deleted like this.

    DELETE /artist/BartSimpson

d)  You can query on existing attributes of the artist.

    GET /artist?eye-color=Blue

    <artistlist>
        <artistref href="/artist/LisaSimpson">Lisa Simpson</artistref>
        <artistref href="/artist/Madonna">Madonna</artistref>
    </artistlist>

    GET /artist?name=Lisa%20Simpson

    <artistlist>
        <artistref href="/artist/LisaSimpson">Lisa Simpson</artistref>
    </artistlist>

    These queries can be generated by an HTML Form. The query part
    of a URL is not opaque to the User Agent. The client is expected
    to provide query parameters for use in searches.

    Note that the http path, before the query, is still opaque.
    It could be /artist or /search or /cgi-bin/artistquery.cgi.
    However, I believe that the prefered restful practice is to direct
    the query to the collection URL, /artist in this case, and map this
    to the search utility, typically by an entry in the htaccess file.

e)  You can have arbitrary lists of artists.

    GET /artistlists/my-favorites

    <artistlist title="My favorite artists">
        <artistref id="./LisaSimpson" href="/artist/LisaSimpson">Lisa
Simpson</artistref>
        <artistref id="./BartSimpson" href="/artist/BartSimpson">Bart
Simpson</artistref>
    </artistlist>

    Note that each item in the list has its own URI.

    An entry in this list can be deleted like this:

    DELETE /artistlists/my-favorites/BartSimpson

    An entry can be added to this list like this:

    POST /artistlists/my-favorites

    <artistref href"/artist/BartSimpson">Bart Simpson</artistref>


Points of note
--------------

1.  URIs are always generated by the origin server.

2.  The client only calculates a URI in two circumstances:
     a) it converts relative URIs, generated by the origin server,
        into absolute URIs
     b) it may add query parameters to the end of a search
        URI provided by the origin server.

3.  All xml elements that can be addressed individually are provided
    with a relative URI by the origin server.

I think this approach is restful, but I have thought that before and been
wrong.
I have not seen it suggested before, however, I have not trolled the archive
so I
cannot be certain.

Although I have not attempted it, it should be possible to process all the
xml above into HTML using a suitable transform or style sheet.

I hope you find this interesting and maybe even helpful.
Regards
Donald.

> -----Original Message-----
> From: David Orchard [mailto:orchard@...]
> Sent: Thursday, 3 June 2004 9:33 AM
> To: rest-discuss@yahoogroups.com
> Subject: [rest-discuss] Identifiers: higher precedence than other
> fields?
>
>
> I was further thinking about modeling of identifiers in xml
> versus URIs and the use of them in relation to other fields for
> queries.  It seems that any XML identifier is problematic to
> algorithmically map to a URI.
>
> My scenario: I have an Artist List structure containing Artist
> structures with a Name and an uri reference, ie
> <ArtistList><Artist><Name>Thievery
> Corp</Name><URI>http://www.eslmusic.com/artists/thievery.html</URI
> ></Artist></ArtistList>
>
> I want to support getting the entire Artist information, or just
> a single field.  We earlier said that making the Artist
> identifier hierarchical is a Good Thing.  This would look like:
>
> GET /ArtistList/Artist/id/xyz.
>
> But in my xml data structure, I specified that the Name structure
> uniquely identifies the band in my database.  I end up having 2
> primary keys: one if I use URIs, and another if I were to do an
> XML based query.  If I used the Name as the key, the URI looks more like
>
> ./Artist/Name/Thievery%20Corp
>
> If I then want to get the value of the URI field where the
> Artist=Thievery Corp, my query might look something like:
>
> GET /ArtistList/Artist/Name/Thievery%20Corp/URI
> or
> GET /ArtistList/Artist/Name/Thievery%20Corp?field=URI
>
> I prefer the former because the URI field is hierarchical within
> the Artist structure, it's just that the darned Name messes up
> the hierarchy.  I don't want to use client side identifiers, ie
> fragment ids such as Artist#ThieveryCorp or even
> Artist/Name/Thievery%20Corp#thievery%20CorpURI
>
> So I then thought in cases where the field being requested was at
> the same or lower level than the identifier, I could use the path
> component to specify the Artist, as in
>
> GET /ArtistList/Artist;Name=Thievery%20Corp/URI
>
> Which I'd interpret as for the Artist who's name field is
> thievery corp, get the URI field.  I wonder if this is a good way
> of modelling the query?
>
> I think you should now have the rough gist of the way that I'm
> thinking about binding xml structures to URIs, and this has led
> to some questions:
>
> 1. What is the best design, or even the trade-offs to be made
> across designs, when binding xml identifiers to URIs
>
> 2. How should requests for a "secondary resource" in a component
> be expressed when the secondary resource is at the same level in
> the xml hierarchy as the xml identifier.
>
> I wasn't quite sure which way Roy was saying is the best way
> given the different examples of
http://example.com/quotes/${exchange}/${symbol} and  /Artist/id/12345678.
That is, whether the URI for the resource is parameterizable and thus
generated by a client, or whether the identifier is opaque and the client
has to do a 2nd pass to get it.  It seems like there's an important point
about naming of resources, which is that maybe the xml way of identifying
resources doesn't work well with the Web.

Thanks again for all your time,
Dave

> What I was tring to say, in my clumsy way, is that the approach I was
describing
> uses completely opaque paths that are always generated by the origin
server.
> There is no requirement for an User Agent to calculate the paths and
consequently
> the origin server can use any naming convention it wants to.
Oh. I guess I read it too quickly.


> As far as using external sources for generating references to resources,
as you
> describe above, the way I would do that is to query the system to
determine
> whether such an artist exists. So for example, the phone book lists a
> "Lisa B Simpson" which could be used like this.
>
>    GET /artist?name=Lisa%20B%20Simpson
You'll still have to generate the URI on the client - why not just use
"/artist/Lisa%20B%20Simpson" directly?
Sure, the HTML FORM element only provides a way to construct query terms in
a URI, but several people would like to go beyond that. Really wish we had a
standardized syntax & sample libraries...

>
> The http path, /artist, suggests that only one artist should be returned,
Not sure if that's a safe assumption. I suppose it's a reasonable guess -
but I would easily implement something of similar naming that would return a
list.