Different representations of the same resource

[Jan Stenberg]

I have a need to represent the same resource, e.g. a Student, in two forms; as a full representation with all data, and as a smaller representation with just name and address.

How do I differentiate between the two types of representation?

• As different resources
  
• With an extension to the uri
  
• With different media types, using some sub-type on the base type
  

or some other way?

To differentiate between XML and JSON representations we're using the media type; application/vnd.ladok+xml and application/vnd.ladok+json respectively

Thanks,

Jan

[Rushforth, Peter]

Hi Jan,

 

We have used a media type parameter.  Where you 'own' the media type this is workable.  For text/html say,

it may be a stretch.  Adding a parameter to that is a hack, but IMHO a useful one, thanks to 'must ignore'.

 

From the REST POV, the key is that the client and server understand the format (s), and that references

to the short / long form are embedded in the response leading to that resource can be differentiated,

using for example (pretending that application/vnd.ladok+xml is based somehow on atom):

 

<atom:link rel="self" type="application/vnd.ladok+xml;form=long" href="..."/>

<atom:link rel="alternate" type="application/vnd.ladok+xml;form=short" href="..."/>

 

Cheers,

Peter

 

---

From: restinp...@googlegroups.com [mailto:restinp...@googlegroups.com] On Behalf Of Jan Stenberg
Sent: September 11, 2013 08:03
To: restinp...@googlegroups.com
Subject: Different representations of the same resource

--
You received this message because you are subscribed to the Google Groups "restinpractice" group.
To unsubscribe from this group and stop receiving emails from it, send an email to restinpractic...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Jim Webber]

Hello Jan,

I see no contradiction in having two resources (which is the same as having an extension for the URI since they are both therefore URIs) for this, e.g.

GET /student

{ name : "Jan", age "classified", address : "Umeå"}

and

GET /student/address

{ address : "Umeå"}

And obviously the same content can be serialised in XML just as readily, which you use content negotiation for.

Jim

[Harry Friemann]

I have the same question, but originating from the point of partial updating.

If I, for example, would be allowed to do:

GET /student         Allow: application/vnd.ladok+json                         to get { name : "Jan", age "classified", address : "Umeå"} 

GET /student         Allow: application/vnd.ladok-name+json               to get { "name" :  "Jan" }

could I, obeying REST, also do the following?

PUT /student      Content-Type:  application/vnd.ladok-name+json     with body { "name" :  "Kees" }

I am putting the whole representation of described by the media type here.

So, I want to use two different media-types on the same endpoint and update data by using PUT.

[Jim Webber]

Hi Harry,

That doesn't seem right to me. If you want a name, then mint a URI for it, and keep using the same media type.

> GET /student Allow: application/vnd.ladok+json to get { name : "Jan", age "classified", address : "Umeå"}

> GET /student/name Allow: application/vnd.ladok+json to get { "name" : "Jan" }

Then you get the benefits of being able to individually cache, authorise, and so on.

Jim

[Harry Friemann]

Ok, I understand when this would be a clean 'name'.

But let me make myself more clear.

I am actually doing something like this with an attribute called 'state'.

I tried to make 'state' a subresource so {something}/state

When I do a get I may get something like:

GET {something}/state

MediaType X

{

      state : "Submitted",

      submittedBy : "Jan",

      subMittedAt : "29-11-2013T16:03:00.000Z"

}

What I want is to do:

PUT {something}/state

{

     state :  "Processes"

}

So I do not want to include the By/At data perse.

The question is, when I define a media-type Y (which is a subset of X btw), with just the state, 

is it conform PUT rfc / REST expectations, since I do PUT the whole Y representation?

-Harry

[Jim Webber]

Hi Harry,

The last time I came across this notion of "partial PUT" it was hotly debated. Mark Baker and Mark Nottingham (a couple of very influential Web folks) could not reach agreement with Baker (IIRC) saying that partial PUT is OK, while Nottingham was aghast at the concept.

In general PUT has replace semantics, and so to sidestep the unresolved Mark vs Mark dispute, I would still argue that you should expose another resource and PUT to that.

Jim

[Jørn Wildt]

You could also use something like PATCH for partial updates. See for instance http://soabits.blogspot.dk/2013/01/http-put-patch-or-post-partial-updates.html

/Jørn

Jim

[Jim Webber]

But then you need to agree on the patch format too. Has anyone actually used PATCH in the wild?

Jim

[Josh Graham]

In the spirit of "tell-don't-ask" and avoiding drifting toward distributed objects, I would expect their to be links from your main resource with relationships like "process" to another (possibly sub-) resource that you POST to.

This conveys the semantics of externally messagable state transition, rather than externally mutable state, while being spot-on REST, and using HATEOAS.

I would avoid the "state" sub-resource unless the main resource has an unwieldy number of attributes. But if you did, it might look like this (excuse not real JSON and HAL syntax from phone) :

GET /widget/123/state

{

 state: submitted,

 _links: {

  process: https://me.com/widget/process/123

 }

}

POST /widget/process/123

202 Accepted

Location: /widget/123

GET /widget/123/state

{

 state: processing,

 _links: {

  cancel: https://me.com/widget/cancel/123

 }

}

POST /widget/process/123

200 OK

Location: /widget/123

GET /widget/123/state

{

 state: processing,

 _links: {

  cancel: https://me.com/widget/cancel/123

 }

}

GET /widget/123/state

{

 state: complete,

 _links: {

  cancel: https://me.com/widget/cancel/123

 }

}

POST /widget/process/123

409 Conflict

Location: /widget/123

See, a lovely simple protocol with no messing around with partial PUTs or PATCHes.

JoshG

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

From the phone

--

[Jørn Wildt]

Yes, we have (cBrain). Works fine. See the blogpost i referred.

Regards, Jørn

--
/Jørn