Detailed feedback thread: 2-OpenSocial_0_8_API_Spec.html

[Dan Peterson]

As per below, please use this thread to discuss potential improvements to the OpenSocial API spec (v0.8):
http://opensocial-and-gadgets-spec.googlegroups.com/web/2-OpenSocial_0_8_API_Spec.html

Thanks,
-Dan

---------- Forwarded message ----------
From: Dan Peterson <dpet...@google.com>
Date: Fri, May 9, 2008 at 6:27 PM
Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related spec updates
To: opensocial-and-gadgets-spec <opensocial-an...@googlegroups.com>


Hi folks,

As discussed last week, the full draft of OpenSocial v0.8 specification is ready for your review. This draft specification includes updates to existing specs, inclusion of the RESTful spec, release notes, and detailed JavaScript doc (JSDoc). The intent was to clearly capture all of the 40+ changes/additions that we have developed on this mailing list since version 0.7 of the spec (as tracked in http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). Let's use the next week or two to make improvements to these docs and then we can lock down 0.8.

You can find all 6 of these documents uploaded into the "Files" section of this Google Group: http://groups.google.com/group/opensocial-and-gadgets-spec/files?&sort=name

The draft documents published are (please note that some of the links in the files might not work as this is only a staged copy):

• 1 - OpenSocial 0.8 Release Notes
• 2 - OpenSocial 0.8 Specification
• 3 - OpenSocial 0.8 RESTful API Specification
• 4 - gadgets Specification
• Canonical gadgets XSD
• Extended gadgets XSD
• gadgets Message Bundle XSD
  
• 5 - opensocial.* 0.8 JS doc
• 6 - gadgets.* JS doc

I have conveniently numbered these documents so it is easier for you to walk through them in a clear order. In addition, documents 1 through 4 have their additions/updates highlighted for ease of reference. To better organize detailed feedback for each document, I will now start a thread for each of the 6 documents. Please be sure to direct your feedback to the appropriate thread.

Also, as a reminder, this coming Wednesday, May 15, we'll be holding an OpenSocial Summit in Mountain View, California. This event is an ideal opportunity to discuss this draft specification, propose ideas for future iterations, and learn about the latest happenings in the community -- as well as get to know each other in person.

You can learn more about the event at: http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th-at.html
The agenda is here: https://docs.google.com/View?docID=dds2mvj3_1vxvsnzfd
(RSVP is here: http://spreadsheets.google.com/viewform?key=pKy6PfiaRD2NIEhpx692Oaw )

Looking forward to your feedback (in the appropriate thread ;),
-Dan

[Kevin Brown]

"The container must support the RESTful API specification". Why is this "MUST"? What if my container is an iphone? What if it's a desktop application? Are these containers forbidden from claiming to support opensocial-0.8, even if they currently support opensocial-0.7 correctly?

The "Views" section here belongs in the gadgets spec reference (see my other email about views being an incredibly vague concept in the gadget docs). I strongly suggest that these be a single document (or set of tightly coupled documents). Either these things are separate specifications, or they're not, so the specifications for how views work belong where they're defined. Same for other gadgets-related stuff.

The tone of this document is also not really appropriate for a specification. It's excellent as a developer's guide or platform overview, but it's very difficult to approach without a concrete reference. It also makes making change proposals very difficult. My suggestion is to add a separate document that takes a more traditional approach -- provide identifiers for sections and sub-sections, and have concrete terminology across the board (MAY, SHOULD, MUST, MAY NOT). This will help eliminate the ongoing compatibility problems we see with containers that have implemented opensocial-0.7 and 0.8.

This document is also lacking in anything explaining how the opensocial js even gets used in the context of a gadget. In practice, containers have implemented what is mentioned in the developer's guide, but the developer's guide is not the specification. Am I still a compliant opensocial container if I make developers include an external javascript file to support the specified opensocial libraries? Based on the current spec, that looks valid.

[Gary Helmling]

"Key Concepts" section:
The RESTful API spec defines Groups in section 2.3, while this spec
only refers to "Relationships". It seems like the definitions and
terminology should be consistent. Groups are also not explicitly
defined in the Javascript API spec, only referenced indirectly in the
VIEWER_FRIENDS and OWNER_FRIENDS keywords (which are not explicitly
defined in an enum).

[Paul Lindner]

I had a pretty extensive writeup of the lifecycle events should this
be included here?

http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/64f588e6daa72b0f/2d4df2b44049dbdc?#2d4df2b44049dbdc

Can we integrate some wording on refreshInterval from this documents:

http://code.google.com/support/bin/answer.py?hl=en&answer=76404

into the section on gadgets.io.makeRequest() ?

Caching can't be reiterated enough..

On Fri, May 09, 2008 at 06:31:16PM -0700, Dan Peterson wrote:
> As per below, please use this thread to discuss potential improvements to
> the OpenSocial API spec (v0.8):
> http://opensocial-and-gadgets-spec.googlegroups.com/web/2-OpenSocial_0_8_API_Spec.html
>
> Thanks,
> -Dan
>

> From: Dan Peterson <dpet...@google.com>
> Date: Fri, May 9, 2008 at 6:27 PM
> Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related
> spec updates
> To: opensocial-and-gadgets-spec <
> opensocial-an...@googlegroups.com>
>
>
> Hi folks,
>
> As discussed last week, the full draft of OpenSocial v0.8 specification is
> ready for your review. This draft specification includes updates to existing
> specs, inclusion of the RESTful spec, release notes, and detailed JavaScript
> doc (JSDoc). The intent was to clearly capture all of the 40+
> changes/additions that we have developed on this mailing list since version
> 0.7 of the spec (as tracked in
> http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ).
> Let's use the next week or two to make improvements to these docs and then
> we can lock down 0.8.
>
> You can find all 6 of these documents uploaded into the "Files" section of
> this Google Group:
> http://groups.google.com/group/opensocial-and-gadgets-spec/files?&sort=name
>
> The draft documents published are (please note that some of the links in the
> files might not work as this is only a staged copy):
>

> - 1 - OpenSocial 0.8 Release Notes
> - 2 - OpenSocial 0.8 Specification
> - 3 - OpenSocial 0.8 RESTful API Specification
> - 4 - gadgets Specification
> - Canonical gadgets XSD
> - Extended gadgets XSD
> - gadgets Message Bundle XSD
> - 5 - opensocial.* 0.8 JS doc
> - 6 - gadgets.* JS doc

>
> I have conveniently numbered these documents so it is easier for you to walk
> through them in a clear order. In addition, documents 1 through 4 have their
> additions/updates highlighted for ease of reference. To better organize
> detailed feedback for each document, I will now start a thread for each of
> the 6 documents. Please be sure to direct your feedback to the appropriate
> thread.
>
> Also, as a reminder, this coming Wednesday, May 15, we'll be holding an
> OpenSocial Summit in Mountain View, California. This event is an ideal
> opportunity to discuss this draft specification, propose ideas for future
> iterations, and learn about the latest happenings in the community -- as
> well as get to know each other in person.
>
> You can learn more about the event at:
> http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th-at.html
> The agenda is here: https://docs.google.com/View?docID=dds2mvj3_1vxvsnzfd
> (RSVP is here:
> http://spreadsheets.google.com/viewform?key=pKy6PfiaRD2NIEhpx692Oaw )
>
> Looking forward to your feedback (in the appropriate thread ;),
> -Dan
>

> 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
> -~----------~----~----~----~------~----~------~--~---
>

--
Paul Lindner ||||| | | | | | | | | |
lin...@inuus.com

[Kevin Brown]

I believe these belong in the gadget rendering and gadget js API docs, respectively.

[Paul Lindner]

On Wed, May 14, 2008 at 02:57:43AM -0700, Kevin Brown wrote:
> I believe these belong in the gadget rendering and gadget js API docs,
> respectively.

Commented on the js API docs for REFRESH_INTERVAL

Since lifecycle is OpenSocial specific I believe it needs to be
documented here...

[Cassie]

On Sat, May 10, 2008 at 12:02 PM, Kevin Brown <et...@google.com> wrote:

"The container must support the RESTful API specification". Why is this "MUST"? What if my container is an iphone? What if it's a desktop application? Are these containers forbidden from claiming to support opensocial-0.8, even if they currently support opensocial-0.7 correctly?

I believe, the only thing you actually have to do in order to support rest is to host a discovery xml file which says which urls you support. And, in the tradition of opensocial where you can respond "not implemented" to everything, i believe you can simply not include any supported urls in your discovery file.

So... in order to support rest, I believe all you really need is a nearly-empty xml file to be hosted. Technically, this sounds pretty easy and thus I have no issues whatsoever saying that you have to be able to serve up an xml file saying which rest urls you support.

We already agreed on this on the individual spec thread and if it poses no technical restrictions than I think we are fine.
What do you think?

- Cassie

 

[John Hjelmstad]

I think Kevin's concerns are valid, and you raise an interesting point, but it's still sorta lame to require a do-nothing discovery XML file on a device... and I don't think we have to while still retaining the value we want.

My view is that this document's ultimate purpose - the purpose of OpenSocial itself - is to define as standardized an environment as possible in which Apps run. RESTful is an incredibly important piece of that, and softening "MUST" in clause #4 opens the door to incompatibility. A key observation to make, IMHO, is that this document is scoped to "social websites" right in its prologue. So, I think it's fair to keep it as-is for now.

This does mean that strict v0.8 compliance is indeed limited to social websites. That does close the door to phones, desktop, etc claiming to be OpenSocial containers. But they can still "support" OpenSocial. In practice I doubt this limitation will be a big deal as long as we (keep) support(ing) any and all efforts to perpetuate OpenSocial Apps everywhere we can get them. Once we have more experience with what those requirements will be, we'll be better equipped to add concrete compliance text for them in v0.9.

2c,
John