High-level proposal to align OpenSocial and PortableContacts technical specs

[John Panzer]

As you all know, a major goal of OpenSocial is to foster widespread adoption of a standard API for social sites and applications. Recently, another open specification project called PortableContacts, rapidly gaining traction with many large service providers as well as the open grass-roots community, has been developing a standard with a narrow/deep focus on giving users access to address book and friends-list info. Since we share the goal to develop and advocate for a *single* standard, and avoid the potential for fragmentation that motivated OpenSocial initially, and since the two specs are actually very similar at a technical level for their overlapping portions, we've been talking informally about how best to converge the existing OpenSocial RESTful spec and the PortableContacts spec.

 

As a result of these offline talks there are a set of proposals about to be sent to both spec lists to actually accomplish the alignment.  Consider this email a broader heads up for several technical proposals designed to bring the specs into complete alignment.

The high level proposal:

If you implement a OpenSocial 0.8 service you are automatically technically compliant with PortableContacts.
Roughly, the People-only, read-only, JSON-only subset of OpenSocial's REST API is exactly the same as PortableContacts
and it is our intent going forward to maintain compatibility between Portable Contacts and the related subset of the OpenSocial RESTful API

Stay tuned for more technical proposals to follow shortly, hopefully none of which will be too controversial.

Thanks!

Joseph Smarr & John Panzer

[Joseph Smarr]

Hi everyone, I've now posted a detailed technical description of the changes we're proposing to the OpenSocial RESTful spec: http://docs.google.com/View?docid=dchtjj6f_3fw2b95d9. I've already gone through several revisions of this doc with feedback from various OpenSocial folks, so hopefully there's nothing too confusing or outrageous here. That being said, if you're passionate about the details of the RESTful API--particularly in terms of ease/burden of adoption--please take a look and share your feedback!

My hope is that we can quickly identify any confusion/disagreement about these proposed changes, tweak the proposal as needed, and then submit the changes to an official vote. Assuming there are no major surprises, we'll plan to put this up for a vote sometime next week. If some areas prove more contentious than others, we may break up the proposal into a few separate chunks, so the easy stuff can be approved sooner while we resolve any remaining issues. In other words: please dive in now, and let's move fast and be pragmatic.

BTW, for those interested in following the related progress of the PortableContacts spec, we're currently making a corresponding (and deeper) set of changes to align it with the overlapping portion of OpenSocial, and we'll post an updated draft spec to http://portablecontacts.net soon. Our goal is to soon end up with a best-of-breed standard language for who-you-know data that can be widely implemented by a large number of services, and that anyone working on implementing the OpenSocial RESTful APIs will be able to participate in this world without having to do any additional work!

Thanks, js

[Chris Chabot]

The spec changes them selves look good at first glance. My concern is more one about timing.

There is some discontention about the current RESTful specification and i don't feel it's stable enough yet to be able to vote on an extension on it that further ties us to the current state of it.

There is number of (sizable) containers holding off on the RESTful wire format based on their feeling that the RESTful API isn't quite 'complete' yet, there is an supplemental JSON-RPC spec proposed because of gadget developers indicating that they think the current spec is to complex, and i personally think it's to complex for the joe.blow end user gadget developer too, and i don't agree with the assumption that 'early adopters will write libraries for the rest to use' as a solution to the complexity. The fact no one has really started working on it for over 2 months alone is probably a small sign too.

I think it's a good time to discuss this proposal, but I would suggest waiting a little with voting for it until other things have some time to bake and circulate, otherwise it might only add complexity to an already complex situation and delay things even more.

My humble $0.02

-- Chris

[Eiji Kitamura]

Hi, Joseph

I've been looking forward to seeing PortableContacts spec and
worndering how different PortableContacts is against OpenSocial
RESTful spec. It's good to hear that there was consideration and
discussion between them.
I'm really excited to imagine how our service can get enpowered by
PortableContacts :)

But for now, as a future container holder, I'm with Chris.

Since our team is developing OpenSocial container using Shindig, any
delay of its release will affect our plan.
I was assuming Shindig to be version 1.0 (released branch) within August.
If shindig's going to be delayed, we will have to release our
container without restful api (as v0.7 or v0.8 with wire format which
requires additional development to us).

I hope at least, adoption of PortableContacts implementation to
shindig will be after release of version 1.0, if spec allows.

Eiji

2008/7/18 Chris Chabot <cha...@xs4all.nl>:

[Joseph Smarr]

Eiji and Chris-thanks for the quick feedback!

 

I've been speaking with some of the main shindig implementors while working on this spec change, and while I don't want to put words in their mouth, I didn't get the sense that anything proposed here is going to slow them down significantly. Implementation-wise, most of the changes are just little cleanups and clarifications, with a few slightly larger items like adding support for basic filtering. And furthermore, the RESTful API is the same backend that will power the JS API, so shindig-wise, it's not "extra work" to support the RESTful API (as I understand it), it's the work they'd be doing anyway to support gadget containers.

 

I certainly understand your desire to ship quickly, and it is definitely not my intention to slow things down here. But if we're going to make these changes at some point, I do believe it will be minimally painful to make them now, before you have lots of developers and downstream code relying on your API looking a certain way that all need to change their code as well. So while changing the spec now might slow things down a touch, I think it would slow them down even more to delay making these changes.

 

Thanks, js

[Chris Chabot]

On Jul 18, 2008, at 5:24 PM, Joseph Smarr wrote:

> I've been speaking with some of the main shindig implementors while
> working on this spec change, and while I don't want to put words in
> their mouth, I didn't get the sense that anything proposed here is
> going to slow them down significantly.

Odd, the I'm the furthest along with actually implementing the RESTful
spec (in the PHP version of shindig), probably the deepest at the
moment into it's practical implications on shindig's code base (as i
almost have it completed), and we didn't really speak about this..

[Chris Chabot]

http://www.ohloh.net/projects/10942/contributors

[Joseph Smarr]

Chris-I guess I was mainly talking to local google employees who contribute to shindig, my bad. :) I would love to talk more with you about how the RESTful implementation is going in shindig, and what you're running up against. And bonus points for working on the PHP version (Plaxo Pulse is all PHP, including the OS REST work we've done to integrate with FriendConnect, and our PortableContacts implementation)! :) Let's try to find some time offline to chat.

Thanks! js

[Chris Chabot]

From what i understand (i haven't had the pleasure to play with friendconnect yet) is that it uses the read only, json format of the RESTful API. We've had that part done in shindig for over 2 months already, so that's not where we have any issues :)

My personal main issue with the REST spec is largely that it is too ambiguous (and only 1 or 2 technical qualms):

It doesn't define if different formats can be mixed in batched requests in the input 

It doesn't define if different formats can be mixed in batched requests output (by including ?format=foo in the parts?)

It doesn't define clearly that a post to /people/{id}/@all doesn't create a person, but that it creates a friendship relationship (request)

It doesn't define clearly what format is expected in the "person representation elided", nor does it define if that's a full person object, some search fields (which j.panzer later explained in email), or what exactly..

It doesn't define that content-type: application/{atom,json} is the way to tell what format the representation for the part in a batch is in

It doesn't define how to define the input format in a single put/post request either (presumably also content-type btw:P)

It defines that -ALL- object fields should be returned when no fields are specified (see previous thread, that's negative on performance and bandwidth)

It conflicts on a few points with the JS API, and inconsistency makes for a bad spec imo.

It doesn't include enough examples to give end users a running start on using it

I personally think depending on XRDS Simple is not so 'simple' for the average developer (see my xrds-json counter proposal :)

It depends on multipart/mixed posting which is quite difficult to do in a well maintainable & stable way in many languages (including php)

Well that's just my personal list ... There are also sounds from (large) gadget developers who think the spec is to complicated (but thats hearsay so i won't hammer to strongly on it), and container implementers who tell me directly that they don't trust the RESTful API spec yet and prefer to keep using the 0.7 wire format.. Both of which get in the way of large scale adaptation too.

So that's why my reaction to the OpenSocial / PortableContacts alignment proposal was one of "let's wait to see what happens first", it's not that it's so complicated to rename some fields or make a few relatively minor changes but being "Portable Contacts" compliant does add another layer of dependencies that i would rather save until after the above is settled (or at least had a chance to see if those things can be addressed)

-- Chris

[Dan Peterson]

Hey folks,

There is some good discussion here, and on the process point, I don't think we should let the timeline of Shindig influence the evolution of the spec. The two are intentionally independent.

How about we have any changes that result from this proposed alignment be labeled as part of "v0.8a"? While apparently not huge deltas (so 0.9 seems overkill), it provides a clean mechanism for Shindig, or any other implementation, to describe what is (or is not) being implemented.

 

-Dan

 

On Thu, Jul 17, 2008 at 7:01 PM, Eiji Kitamura <age...@gmail.com> wrote:

[Chris Chabot]

Hey Dan,

Moving to a 0.8a spec seems like a good idea to me. It gives us the opportunity to merge in Joseph Smarr & John Panzer's work on the PortableContacts alignment, and hopefully allow us to address a few of the outstanding issues with the current spec too, without having to wonder if we're allowed to change it after it's backed or not.. which can only be positive from a progress point of view.

Has my +1

-- Chris

[Eiji Kitamura]

+1 with 0.8a idea.
I prefer 0.8.1 though :)

2008/7/19 Chris Chabot <cha...@xs4all.nl>:

[Louis Ryan]

In general I would agree but I think deferring reference implementations has seriously hurt the quality of the OpenSocial specifications. In general I think folks would rather see sample implementations in Shindig BEFORE proposal are made to the spec where possible. This will greatly help the credibility of both Shindig and any future specs and avoid the extended vacuum effect between release of specs and release of features. At the very least no spec should be considered final until we have some kind of implementation.

[John Panzer]

"At the very least no spec should be considered final until we have some kind of implementation."

+1, meaning that 0.8a can proceed but can't commit until we have sufficient running code to verify the rough consensus.

John Panzer (http://abstractioneer.org)

[Joseph Smarr]

Agreed, and my hope is that we could quickly start implementing the PortableContacts changes in Shindig (assuming there aren't any major objections to what's proposed, which so far there aren't), and that would both reveal any implementation issues and also "make it real" so we could both finalize the spec and ship code to people to start using it. :)

Thanks, js