REST API versioning suggestions for OpenSocial

[Niels van Dijk]

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]

There is an open spec specification issue for this.

http://code.google.com/p/opensocial-resources/issues/detail?id=1146 

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]

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]

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]

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