Different representations of the same resource

92 views
Skip to first unread message

Jan Stenberg

unread,
Sep 11, 2013, 8:03:13 AM9/11/13
to restinp...@googlegroups.com
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

unread,
Sep 11, 2013, 8:48:07 AM9/11/13
to restinp...@googlegroups.com
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

unread,
Sep 11, 2013, 8:49:53 AM9/11/13
to restinp...@googlegroups.com
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

unread,
Nov 29, 2013, 2:55:51 AM11/29/13
to restinp...@googlegroups.com
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

unread,
Nov 29, 2013, 7:59:39 AM11/29/13
to restinp...@googlegroups.com
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

unread,
Nov 29, 2013, 10:07:43 AM11/29/13
to restinp...@googlegroups.com
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

unread,
Nov 29, 2013, 4:15:34 PM11/29/13
to restinp...@googlegroups.com
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

unread,
Nov 29, 2013, 4:19:57 PM11/29/13
to restinp...@googlegroups.com
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

unread,
Nov 29, 2013, 5:19:17 PM11/29/13
to restinp...@googlegroups.com
But then you need to agree on the patch format too. Has anyone actually used PATCH in the wild?

Jim

Josh Graham

unread,
Nov 29, 2013, 10:59:37 PM11/29/13
to restinp...@googlegroups.com, restinp...@googlegroups.com
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: {
 }
}

POST /widget/process/123
202 Accepted
Location: /widget/123

GET /widget/123/state
{
 state: processing,
 _links: {
 }
}

POST /widget/process/123
200 OK
Location: /widget/123

GET /widget/123/state
{
 state: processing,
 _links: {
 }
}

GET /widget/123/state
{
 state: complete,
 _links: {
 }
}

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

unread,
Nov 30, 2013, 12:51:21 AM11/30/13
to restinp...@googlegroups.com
Yes, we have (cBrain). Works fine. See the blogpost i referred.

Regards, Jørn


--
/Jørn
Reply all
Reply to author
Forward
Message has been deleted
0 new messages