zoom

28 views
Skip to first unread message

Andrei Neculau

unread,
Oct 10, 2012, 3:59:55 AM10/10/12
to api-...@googlegroups.com
In https://vimeo.com/49609648, Matt talks about the zoom functionality.
It looks like the representation types are not versioned, correct?

For those that cannot afford not-versioned representations though, how would that look: zoom=price-v2 ?
That doesn't really work since what you want is to zoom into price, and get the v2 representation of price.
It gets more obvious with a level 2: zoom=price.currency (imagine that for some reasons currency would be a versioned representation)

Do you then switch to media-type parameters?
GET ...?zoom=price
> Accept: application/vnd.a.item-v1;price=price-v2

And beyond that, am I the only one that understands Matt's talk on query-string, in conjunction with zoom as:
1. POST /items?zoom=price // this request will create an item
2. create the item at /items/123
3. return 201 with Location /items/123?zoom=price

Cheers,
Andrei

Matthew Bishop

unread,
Oct 10, 2012, 12:50:43 PM10/10/12
to api-...@googlegroups.com
Versioning and zoom, interesting topic. My thoughts are very much in line with Steve Klabnick's post here: https://secure.designinghypermediaapis.com/nodes/fdivisitjqwp

...but you already read that one Andrei ;)


The kind of versioning you are describing is in the rel names, so 'price' links take you to an old price, while 'price-v2' take you to a new price resource. Inside both there might be a 'currency' link to describe the currency of the price.  Two different clients would zoom into two different paths (with results):

GET ...?zoom=price:currency
{
 
':price': {
   
'currency': { ... currency object }
}


and then for the new version
?zoom=price-v2:currency
{
 
':price-v2': {
   
'currency': { ... currency object }
}



The trick is that the items representation would have to surface both links. This is either easy or hard, depending on how links are attached to a representation. The easy way would use something like WRML's 'link formulas' where the links are added by individual strategies via a whiteboard or similar; the hard way woud be to modify /items to have to know about both link relations.


About the second part, I think you are missing a bit:
1. POST /items?zoom=price&followlocation // this request will create an item
2. create the item at /items/123
3. return 201 with Location /items/123 (no ?zoom=price)
as well as the items representation in the body; the representation will have a 'self' field with the zoom in it like this:
{
 
'self': {
   
'uri': '/items/123?zoom=price'
   
...
 
}


 
':price': { //price object }
}


The zoom is part of the URI identifying the representation because it contains injected data from a related resource.

Andrei Neculau

unread,
Oct 11, 2012, 7:18:30 AM10/11/12
to api-...@googlegroups.com
Hmm, I will let this one sink in, Matt.
The surfacing of both links/rels is the easy part. The hard part is digesting versioned relations :) One versioned relation per versioned representation, in the context of minimizing as much as possible the versioning boom..

Thanks for replying so precisely.
Reply all
Reply to author
Forward
0 new messages