REST API versioning suggestions for OpenSocial

16 views
Skip to first unread message

Niels van Dijk

unread,
Feb 2, 2012, 5:48:44 PM2/2/12
to opensocial-an...@googlegroups.com
Hi all,

With the upcoming 2.0 implementation in Shindig 3, some of us may face
the need to have multiple API versions up and running (e.g. OpenSocial
1.0 and OpenSocial 2.0) as we want to make the move from Shindig 2 to 3
easy for our users. Currently -if I am correct - OpenSocial has nothing
on version the REST API, but the gadgets are able to explicitly request
a OS version. Is this by choice? Should the REST API also include some
sort of version? Do we as the spec community consider this an
implementation issue?

thanks!
Niels

Matthew Marum

unread,
Feb 2, 2012, 8:05:37 PM2/2/12
to opensocial-an...@googlegroups.com
There is an open spec specification issue for this.

If you have a proposal, feel free to share it.  

I recall a proposal to add a version segment into the path on URIs.
For example,
/social/rest/v2/people/john.doe/@self

I was concerned with that because it would break any remotely stored links as versions changed.

I'd prefer to use HTTP Headers in requests/responses
OpenSocial-Version:  2.0.0

Optionally allow an OpenSocial version query parameter in requests.
?osversion=2.0.0

Any thoughts?

Matt

Niels

--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.


Matthew Marum

unread,
Feb 3, 2012, 1:36:29 PM2/3/12
to opensocial-an...@googlegroups.com
FYI..
Capturing some discussion that happened in person this morning with Mark and later with James Snell.

There are merits to both approaches, so I think we're going look at supporting both.

James was going to post a specific proposal soon.

Matt

Niels van Dijk

unread,
Feb 4, 2012, 6:55:18 PM2/4/12
to opensocial-an...@googlegroups.com
Hi,

Thanks for you thoughts.

I think all examples are breaking stuff as we're moving from a situation with no version to one that includes a version :( The only option I see from an implementation standpoint is to make the 'v1' version also respond to an unversioned call and instruct remotes to implement a versioned call if they want new features included in 'v2'.

Given that, I agree that adding HTTP Headers would least bother remotes.

It would be nice if the container would also be able to respond if a version mismatch occurs, similar to what the container can do when gadget requests an unsupported version. However I must say I'm not realy in to http headers enough to suggest how that should work.

Cheers,
Niels

Bastian Hofmann

unread,
Feb 5, 2012, 6:17:47 AM2/5/12
to opensocial-an...@googlegroups.com
Hi,

+1 for versioning the api through HTTP headers, but instead of
creating our own custom header, we should just use the "Accept"
header, which was meant to be used for versioning :)

http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

--- Bastian

On Sun, Feb 5, 2012 at 12:55 AM, Niels van Dijk

Reply all
Reply to author
Forward
0 new messages