Hi, everyone,



I'm a newbie here (though not to REST in general), and the list archives have

been a great help in clarifying my understanding of a lot of REST concepts and

suggesting good design elements. I have one part of my design right now where

I'm unsure what a good RESTful approach would be.



I have resources that support GET and PUT, but contain some parts that clients

are not allowed to modify. (This doesn't seem like an uncommon case; I would

think that navigation links, for example, would typically not be modifiable in a

PUT.) So is it better to:



1. Require clients to submit all the read-only parts unmodified in a PUT, and

respond with an error code if they are absent or altered?

2. Take advantage of the leniency allowed in a server's implementation of PUT to

ignore the read-only elements (or their absence)?

3. Separate read-only elements into a sub-resource that only supports GET? (This

may not be feasible for resources which must be created as a whole.)



or something else?



Second, there are some elements that are modifiable or not depending on the

privileges held by the (authenticated) user. I would think this would be

expressed by a difference in the representation returned to the client, but what

should that difference be? (My representations are XML documents, if there isn't

a more general solution.)



And in a broader sense, I'd like the client to know which elements of the

resource the user can modify, for presentation purposes. Is there a generally

accepted way to do this, perhaps with form templates or XForms?



I'd be interested in any comments or alternative approaches, if I'm just looking

at it from the wrong angle.



Thanks,



   -- Jim

Representations in a request (e.g. PUT or POST) and representations in

a response (e.g. GET or a PUT) need not be absolutely the same. HTTP

servers are not databases that blindly store the data. Using PUT to

update the mutable parts of a resource is perfectly okay. At least, I

don't see anything that breaks HTTP.



Subbu





On Jul 2, 2009, at 8:01 AM, Sam Johnston wrote:



>

>

> Jim,

>

> Typically you would express the overall writeability of a resource

> via OPTIONS (e.g. if you can only GET it's read only), but if you've

> got, say, a template driven website and you only want the body to be

> updated then that's something different.

>

> I would almost certainly NOT be using PUT for this, rather accepting

> POSTs of just the midifiable data (perhaps in HTML forms or some XML-

> based format). If you were to use XML then a GET (with the

> appropriate Accept: header) could return just the parts which are

> modifiable by the client. Optionally you could add information to

> the URL about whether the client wants just the writeable elements

> or the whole lot, or even markup the elements as writable (or not).

>

> Hope that helps,

>

> Sam

>

>

> On Wed, Jul 1, 2009 at 9:42 PM, Jim Edwards-Hewitt

> <jimeh@...>wrote:

>

>

> Hi, everyone,

>

> I'm a newbie here (though not to REST in general), and the list

> archives have been a great help in clarifying my understanding of a

> lot of REST concepts and suggesting good design elements. I have one

> part of my design right now where I'm unsure what a good RESTful

> approach would be.

>

> I have resources that support GET and PUT, but contain some parts

> that clients are not allowed to modify. (This doesn't seem like an

> uncommon case; I would think that navigation links, for example,

> would typically not be modifiable in a PUT.) So is it better to:

>

> 1. Require clients to submit all the read-only parts unmodified in a

> PUT, and respond with an error code if they are absent or altered?

> 2. Take advantage of the leniency allowed in a server's

> implementation of PUT to ignore the read-only elements (or their

> absence)?

> 3. Separate read-only elements into a sub-resource that only

> supports GET? (This may not be feasible for resources which must be

> created as a whole.)

>

> or something else?

>

> Second, there are some elements that are modifiable or not depending

> on the privileges held by the (authenticated) user. I would think

> this would be expressed by a difference in the representation

> returned to the client, but what should that difference be? (My

> representations are XML documents, if there isn't a more general

> solution.)

>

> And in a broader sense, I'd like the client to know which elements

> of the resource the user can modify, for presentation purposes. Is

> there a generally accepted way to do this, perhaps with form

> templates or XForms?

>

> I'd be interested in any comments or alternative approaches, if I'm

> just looking at it from the wrong angle.

>

> Thanks,

>

> -- Jim

>

>

>

>

>

Sounds like the fingerprint, portrait, and scan could all be subordinate

resources. Maybe http://example.com/person/123 returns an HTML or XML document

with several links in it, like:



(excuse my not-exactly-Atom XML)...



<entry>

   <id>http://example.com/person/123</id>

   <link rel="http://example.com/schemas/#portrait"

         href="http://example.com/person/123/portrait

         type="image/jpeg"/>

   <link rel="http://example.com/schemas/#fingerprint"

         href="http://example.com/person/123/fingerprint"

         type="image/jpeg"/>

   ...

</entry>



Etc.



Jon



________________________________________

From: Sam Johnston [mailto:samj@...]

Sent: Monday, July 06, 2009 2:27 PM

To: Moore, Jonathan (CIM)

Cc: Subbu Allamaraju; Jim Edwards-Hewitt; rest-discuss@yahoogroups.com

Subject: Re: [rest-discuss] Resources with read-only and read-write parts



On Mon, Jul 6, 2009 at 7:51 PM, Moore, Jonathan (CIM)

<Jonathan_Moore@...> wrote:

Well, the "[as is]" isn't actually part of the RFC.

Right, which is why I said "The way I read the RFC is..."

The body of the PUT request is simply a *representation* of the state.

Which brings me to a question I considered asking but didn't. REST talks about

representations of resources, where one resource can have multiple

representations.



Let's say I have a person (http://example.com/person/123) and instead of

transferring the person over HTTP (which is not yet possible) I make available

their portrait, fingerprint(s), a scan of their national ID card and some XML

demographics. Where I use distinct content types I can simply PUT a given

representation and have the server side state updated accordingly.



What's the best practice though when portrait, fingerprint and scan are JPGs?

That is, I'm retrieving http://example.com/person/123 with Accept: image/jpeg

but it's impossible to tell whether it's the portrait, fingerprint or scan I'm

after. Similarly, what if I want the fingerprint in PNG?



I immediately start thinking about putting the content-type and/or link-relation

into the URL:



http://example.com/person/123;rel=portrait;type=image/jpeg



Then I start to think about cleaning this up a bit:



http://example.com/person/123/portrait.jpg



But this requires routes/rules and doesn't seem as clean/flexible as it should

be.



Sam



 

On Jul 6, 2009, at 11:42 AM, mike amundsen wrote:



> Keeping in mind that a proliferation of custom media types limits the

> usability of a system, I tend to lean on the side of URIs when

> identifying

> interesting items.



I don't blame custom media types for that. Proliferation of custom

means of expressing semantics limits the usability of the system. A

media type is one of the ways of expressing semantics.



However, this is a contradiction in itself, since most non-browser

applications have custom/non-standard semantics that do not completely

fit standard definitions.



My 2 cents

Subbu

I agree with the inefficiency (it is an inconvenience, to be accurate)

part. That is why, there is no need to require clients to supply the

immutable parts. The "supply everything" requirement usually stems

from XML-schema driven applications, which is unnecessary.



Subbu



On Jul 6, 2009, at 10:28 AM, Sam Johnston wrote:



> On Sun, Jul 5, 2009 at 1:03 AM, Subbu Allamaraju <subbu@...>

> wrote:

>

>> Representations in a request (e.g. PUT or POST) and representations

>> in a

>> response (e.g. GET or a PUT) need not be absolutely the same. HTTP

>> servers

>> are not databases that blindly store the data. Using PUT to update

>> the

>> mutable parts of a resource is perfectly okay. At least, I don't see

>> anything that breaks HTTP.

>>

>

> The way I read the RFC is "*The PUT method requests that the

> enclosed entity

> be stored [as is] under the supplied Request-URI*", which is obvious

> for

> "simple" media types like images where anything else doesn't really

> make

> sense. While it does go on to talk about partial updates (mentioning

> the

> Content-Range header), PUTting a resource in its entirity knowing that

> immutable parts will be ignored and/or trigger errors seems neither

> efficient nor clean to me.

>

> Sam

>

> On Jul 2, 2009, at 8:01 AM, Sam Johnston wrote:

>>

>>

>>>

>>> Jim,

>>>

>>> Typically you would express the overall writeability of a resource

>>> via

>>> OPTIONS (e.g. if you can only GET it's read only), but if you've

>>> got, say, a

>>> template driven website and you only want the body to be updated

>>> then that's

>>> something different.

>>>

>>> I would almost certainly NOT be using PUT for this, rather

>>> accepting POSTs

>>> of just the midifiable data (perhaps in HTML forms or some XML-based

>>> format). If you were to use XML then a GET (with the appropriate

>>> Accept:

>>> header) could return just the parts which are modifiable by the

>>> client.

>>> Optionally you could add information to the URL about whether the

>>> client

>>> wants just the writeable elements or the whole lot, or even markup

>>> the

>>> elements as writable (or not).

>>>

>>> Hope that helps,

>>>

>>> Sam

>>>

>>>

>>> On Wed, Jul 1, 2009 at 9:42 PM, Jim Edwards-Hewitt <jimeh@...

>>>> wrote:

>>>

>>>

>>> Hi, everyone,

>>>

>>> I'm a newbie here (though not to REST in general), and the list

>>> archives

>>> have been a great help in clarifying my understanding of a lot of

>>> REST

>>> concepts and suggesting good design elements. I have one part of

>>> my design

>>> right now where I'm unsure what a good RESTful approach would be.

>>>

>>> I have resources that support GET and PUT, but contain some parts

>>> that

>>> clients are not allowed to modify. (This doesn't seem like an

>>> uncommon case;

>>> I would think that navigation links, for example, would typically

>>> not be

>>> modifiable in a PUT.) So is it better to:

>>>

>>> 1. Require clients to submit all the read-only parts unmodified in

>>> a PUT,

>>> and respond with an error code if they are absent or altered?

>>> 2. Take advantage of the leniency allowed in a server's

>>> implementation of

>>> PUT to ignore the read-only elements (or their absence)?

>>> 3. Separate read-only elements into a sub-resource that only

>>> supports GET?

>>> (This may not be feasible for resources which must be created as a

>>> whole.)

>>>

>>> or something else?

>>>

>>> Second, there are some elements that are modifiable or not

>>> depending on

>>> the privileges held by the (authenticated) user. I would think

>>> this would be

>>> expressed by a difference in the representation returned to the

>>> client, but

>>> what should that difference be? (My representations are XML

>>> documents, if

>>> there isn't a more general solution.)

>>>

>>> And in a broader sense, I'd like the client to know which elements

>>> of the

>>> resource the user can modify, for presentation purposes. Is there a

>>> generally accepted way to do this, perhaps with form templates or

>>> XForms?

>>>

>>> I'd be interested in any comments or alternative approaches, if

>>> I'm just

>>> looking at it from the wrong angle.

>>>

>>> Thanks,

>>>

>>> -- Jim

>>>

>>>

>>>

>>>

>>>

>>>

>>

>>

I agree with the inefficiency (it is an inconvenience, to be accurate) part. That is why, there is no need to require clients to supply the immutable parts. The "supply everything" requirement usually stems from XML-schema driven applications, which is unnecessary.

Subbu

On Jul 6, 2009, at 10:28 AM, Sam Johnston wrote:

On Sun, Jul 5, 2009 at 1:03 AM, Subbu Allamaraju <subbu@...> wrote:

Representations in a request (e.g. PUT or POST) and representations in a
response (e.g. GET or a PUT) need not be absolutely the same. HTTP servers
are not databases that blindly store the data. Using PUT to update the
mutable parts of a resource is perfectly okay. At least, I don't see
anything that breaks HTTP.

The way I read the RFC is "*The PUT method requests that the enclosed entity
be stored [as is] under the supplied Request-URI*", which is obvious for
"simple" media types like images where anything else doesn't really make
sense. While it does go on to talk about partial updates (mentioning the
Content-Range header), PUTting a resource in its entirity knowing that
immutable parts will be ignored and/or trigger errors seems neither
efficient nor clean to me.

Sam

On Jul 2, 2009, at 8:01 AM, Sam Johnston wrote:

Jim,

Typically you would express the overall writeability of a resource via
OPTIONS (e.g. if you can only GET it's read only), but if you've got, say, a
template driven website and you only want the body to be updated then that's
something different.

I would almost certainly NOT be using PUT for this, rather accepting POSTs
of just the midifiable data (perhaps in HTML forms or some XML-based
format). If you were to use XML then a GET (with the appropriate Accept:
header) could return just the parts which are modifiable by the client.
Optionally you could add information to the URL about whether the client
wants just the writeable elements or the whole lot, or even markup the
elements as writable (or not).

Hope that helps,

Sam


On Wed, Jul 1, 2009 at 9:42 PM, Jim Edwards-Hewitt <jimeh@...

wrote:

Hi, everyone,

I'm a newbie here (though not to REST in general), and the list archives
have been a great help in clarifying my understanding of a lot of REST
concepts and suggesting good design elements. I have one part of my design
right now where I'm unsure what a good RESTful approach would be.

I have resources that support GET and PUT, but contain some parts that
clients are not allowed to modify. (This doesn't seem like an uncommon case;
I would think that navigation links, for example, would typically not be
modifiable in a PUT.) So is it better to:

1. Require clients to submit all the read-only parts unmodified in a PUT,
and respond with an error code if they are absent or altered?
2. Take advantage of the leniency allowed in a server's implementation of
PUT to ignore the read-only elements (or their absence)?
3. Separate read-only elements into a sub-resource that only supports GET?
(This may not be feasible for resources which must be created as a whole.)

or something else?

Second, there are some elements that are modifiable or not depending on
the privileges held by the (authenticated) user. I would think this would be
expressed by a difference in the representation returned to the client, but
what should that difference be? (My representations are XML documents, if
there isn't a more general solution.)

And in a broader sense, I'd like the client to know which elements of the
resource the user can modify, for presentation purposes. Is there a
generally accepted way to do this, perhaps with form templates or XForms?

I'd be interested in any comments or alternative approaches, if I'm just
looking at it from the wrong angle.

Thanks,

-- Jim

(I posted this reply privately instead of publicly, so I'm re-posting.)



Ah, that does make it more clear. So I might have two (or more) different

resources/URIs for one behind-the-scenes object, each of which contains only the

elements that the user can modify, which supports GET/HEAD/OPTIONS/PUT?



I like that; it seems much cleaner than the direction I was going.



I think I'd also want to have a resource which contains all the elements and

supports only GET/HEAD/OPTIONS (since, in my case, they're all readable if the

user is authorized to see the resource at all), but I think I'd want it to have

an edit link to navigate to the appropriate read/write resource. Does that mean

that in order to avoid trouble with caching, I'd have to have parallel versions

of that resource with different URIs as well, since the edit link would be

different depending on the user?



  -- Jim



--- In rest-discuss@yahoogroups.com, mike amundsen <mamund@...> wrote:

>

> Jim:

> I am addressing the security portion of your post. Hopefully this

> will give you some ideas.

> <snip>

> there are some elements that are modifiable or not depending on the

> privileges held by the (authenticated) user.

> </snip>

>

> First, I favor managing access rights using a combination of URI +

> HTTP_Method + Auth'ed_User. For example:

> - user1 has GET,HEAD,OPTIONS for /collection/

> - manager1 has GET,HEAD,OPTIONS,POST,PUT for /collection/

> - admin1 has GET,HEAD,OPTIONS,POST,PUT,DELETE for /collection/

>

> This means I focus on defining the proper Resources (addressed via

> URI) when I want to limit what state representations clients and

> server share.

>

> In the case you provide, I would consider different Resources to

> handle different update privileges for the same stored data. This

> also clears up any attempts at doing partial updates (and therefore

> clears up caching issues) since none are needed now that there are

> different resources to handle the details.

>

> In my example, the ability to pass different state representations

> is modeled as different resources. These various "secured" resource

> variations might still all "map" to the same data storage on the

> server, but that's not interesting to the client anyway since the

> data model is *not* the resource model on RESTful implementations.

>

> mca

> http://amundsen.com/blog/

>

>

>

> On Wed, Jul 1, 2009 at 15:42, Jim Edwards-Hewitt <jimeh@...> wrote:

>

> > Hi, everyone,

> >

> > I'm a newbie here (though not to REST in general), and the list archives

> > have been a great help in clarifying my understanding of a lot of REST

> > concepts and suggesting good design elements. I have one part of my design

> > right now where I'm unsure what a good RESTful approach would be.

> >

> > I have resources that support GET and PUT, but contain some parts that

> > clients are not allowed to modify. (This doesn't seem like an uncommon case;

> > I would think that navigation links, for example, would typically not be

> > modifiable in a PUT.) So is it better to:

> >

> > 1. Require clients to submit all the read-only parts unmodified in a PUT,

> > and respond with an error code if they are absent or altered?

> > 2. Take advantage of the leniency allowed in a server's implementation of

> > PUT to ignore the read-only elements (or their absence)?

> > 3. Separate read-only elements into a sub-resource that only supports GET?

> > (This may not be feasible for resources which must be created as a whole.)

> >

> > or something else?

> >

> > Second, there are some elements that are modifiable or not depending on the

> > privileges held by the (authenticated) user. I would think this would be

> > expressed by a difference in the representation returned to the client, but

> > what should that difference be? (My representations are XML documents, if

> > there isn't a more general solution.)

> >

> > And in a broader sense, I'd like the client to know which elements of the

> > resource the user can modify, for presentation purposes. Is there a

> > generally accepted way to do this, perhaps with form templates or XForms?

> >

> > I'd be interested in any comments or alternative approaches, if I'm just

> > looking at it from the wrong angle.

> >

> > Thanks,

> >

> >  -- Jim

> >

> >

Hi Jim,



can you provide an example representation for the mutable/immutable

use case?



Jan



On Jul 1, 2009, at 3:42 PM, Jim Edwards-Hewitt wrote:



> Hi, everyone,

>

> I'm a newbie here (though not to REST in general), and the list

> archives have been a great help in clarifying my understanding of a

> lot of REST concepts and suggesting good design elements. I have one

> part of my design right now where I'm unsure what a good RESTful

> approach would be.

>

> I have resources that support GET and PUT, but contain some parts

> that clients are not allowed to modify. (This doesn't seem like an

> uncommon case; I would think that navigation links, for example,

> would typically not be modifiable in a PUT.) So is it better to:

>

> 1. Require clients to submit all the read-only parts unmodified in a

> PUT, and respond with an error code if they are absent or altered?

> 2. Take advantage of the leniency allowed in a server's

> implementation of PUT to ignore the read-only elements (or their

> absence)?

> 3. Separate read-only elements into a sub-resource that only

> supports GET? (This may not be feasible for resources which must be

> created as a whole.)

>

> or something else?

>

> Second, there are some elements that are modifiable or not depending

> on the privileges held by the (authenticated) user. I would think

> this would be expressed by a difference in the representation

> returned to the client, but what should that difference be? (My

> representations are XML documents, if there isn't a more general

> solution.)

>

> And in a broader sense, I'd like the client to know which elements

> of the resource the user can modify, for presentation purposes. Is

> there a generally accepted way to do this, perhaps with form

> templates or XForms?

>

> I'd be interested in any comments or alternative approaches, if I'm

> just looking at it from the wrong angle.

>

> Thanks,

>

>  -- Jim

>

>

>

> ------------------------------------

>

> Yahoo! Groups Links

>

>

>

The most complicated resource of this type is an Administrator account. The

current representation is:



   <admin>

     <uid>{id}</uid>

     <status>{status string}</status>

     <roles>

       <role>{role-name}</role>

       ...

     </roles>

     <vcard>...</vcard>

     <link rel="http://...#organization" href={org URL} title="{org name}" />

   </admin>



The user may be an ordinary user or a privileged user (leaving aside users with

read-only access, since that case is easy.) An ordinary user can modify the

contact information in the vcard structure, a privileged user can modify the

roles and status (active/disabled/etc.), and the uid is immutable.



(As a further complication, a privileged user can only add or remove roles that

their own account possesses.)



I'm already thinking that my roles may be better expressed as a set of

<role-name> tags with true/false values rather by the presence/absence of a

<role> tag as in the structure above, to avoid ambiguity on PUTs.



   -- Jim



--- In rest-discuss@yahoogroups.com, Jan Algermissen <algermissen1971@...>

wrote:

>

> Hi Jim,

>

> can you provide an example representation for the mutable/immutable

> use case?

>

> Jan

>

> On Jul 1, 2009, at 3:42 PM, Jim Edwards-Hewitt wrote:

>

> > Hi, everyone,

> >

> > I'm a newbie here (though not to REST in general), and the list

> > archives have been a great help in clarifying my understanding of a

> > lot of REST concepts and suggesting good design elements. I have one

> > part of my design right now where I'm unsure what a good RESTful

> > approach would be.

> >

> > I have resources that support GET and PUT, but contain some parts

> > that clients are not allowed to modify. (This doesn't seem like an

> > uncommon case; I would think that navigation links, for example,

> > would typically not be modifiable in a PUT.) So is it better to:

> >

> > 1. Require clients to submit all the read-only parts unmodified in a

> > PUT, and respond with an error code if they are absent or altered?

> > 2. Take advantage of the leniency allowed in a server's

> > implementation of PUT to ignore the read-only elements (or their

> > absence)?

> > 3. Separate read-only elements into a sub-resource that only

> > supports GET? (This may not be feasible for resources which must be

> > created as a whole.)

> >

> > or something else?

> >

> > Second, there are some elements that are modifiable or not depending

> > on the privileges held by the (authenticated) user. I would think

> > this would be expressed by a difference in the representation

> > returned to the client, but what should that difference be? (My

> > representations are XML documents, if there isn't a more general

> > solution.)

> >

> > And in a broader sense, I'd like the client to know which elements

> > of the resource the user can modify, for presentation purposes. Is

> > there a generally accepted way to do this, perhaps with form

> > templates or XForms?

> >

> > I'd be interested in any comments or alternative approaches, if I'm

> > just looking at it from the wrong angle.

> >

> > Thanks,

> >

> >  -- Jim

> >

> >

> >

> > ------------------------------------

> >

> > Yahoo! Groups Links

> >

> >

> >

>

Hey Jim,



On Thu, Jul 2, 2009 at 1:12 AM, Jim Edwards-Hewitt<jimeh@...> wrote:

> I have resources that support GET and PUT, but contain some parts that

> clients are not allowed to modify. (This doesn't seem like an uncommon case;

> I would think that navigation links, for example, would typically not be

> modifiable in a PUT.)



IMO, you seem to be confusing between the state of the resource and

its representation. GET and PUT allow you to retrieve and set the

state of the resource. The data format used for transferring that

state is the media type. "Navigation links" are specific to the media

type and not the state of the resource. I could PUT

application/atom+xml or application/x-www-form-urlencoded and GET

text/html.



--

Sandeep Shetty

http://sandeep.shetty.in/

Ah. That makes a lot of sense, but I don't think I've seen it expressed that way

before. Are there content-type definitions that make that explicit? (I suppose

it mostly applies to xml or html-based formats, where the same type of language

is used to express the state of the resource and the purely content-type

elements.)



   -- Jim



--- In rest-discuss@yahoogroups.com, Sandeep Shetty <sandeep.shetty@...> wrote:

>

> Hey Jim,

>

> On Thu, Jul 2, 2009 at 1:12 AM, Jim Edwards-Hewitt<jimeh@...> wrote:

> > I have resources that support GET and PUT, but contain some parts that

> > clients are not allowed to modify. (This doesn't seem like an uncommon case;

> > I would think that navigation links, for example, would typically not be

> > modifiable in a PUT.)

>

> IMO, you seem to be confusing between the state of the resource and

> its representation. GET and PUT allow you to retrieve and set the

> state of the resource. The data format used for transferring that

> state is the media type. "Navigation links" are specific to the media

> type and not the state of the resource. I could PUT

> application/atom+xml or application/x-www-form-urlencoded and GET

> text/html.

>

> --

> Sandeep Shetty

> http://sandeep.shetty.in/

>

Hey Jim,



On Tue, Jul 7, 2009 at 3:34 AM, Jim Edwards-Hewitt<jimeh@...> wrote:

> Ah. That makes a lot of sense, but I don't think I've seen it expressed that

> way before. Are there content-type definitions that make that explicit? (I

> suppose it mostly applies to xml or html-based formats, where the same type

> of language is used to express the state of the resource and the purely

> content-type elements.)



A form (POST) that accepts only the values that represent the state of

the resource is one way to make it explicit (sigh... if only I could

say method="PUT" path="/foo" in the form tag)



Sandeep Shetty

http://sandeep.shetty.in/





> --- In rest-discuss@yahoogroups.com, Sandeep Shetty <sandeep.shetty@...>

> wrote:

>>

>> Hey Jim,

>>

>> On Thu, Jul 2, 2009 at 1:12 AM, Jim Edwards-Hewitt<jimeh@...> wrote:

>> > I have resources that support GET and PUT, but contain some parts that

>> > clients are not allowed to modify. (This doesn't seem like an uncommon

>> > case;

>> > I would think that navigation links, for example, would typically not be

>> > modifiable in a PUT.)

>>

>> IMO, you seem to be confusing between the state of the resource and

>> its representation. GET and PUT allow you to retrieve and set the

>> state of the resource. The data format used for transferring that

>> state is the media type. "Navigation links" are specific to the media

>> type and not the state of the resource. I could PUT

>> application/atom+xml or application/x-www-form-urlencoded and GET

>> text/html.