Re: Separation of Gadgets and OpenSocial (Option 2)

[jon.we...@gmail.com]

http://codereview.appspot.com/144071/diff/1/2
File draft/Gadgets-API-Specification.xml (left):

http://codereview.appspot.com/144071/diff/1/2#oldcode574
Line 574: <t>sign_owner: gadgets.io.RequestParameters.SIGN_OWNER
(default 'true')</t>
See the comment in the OpenSocial specification on the Views. We can
keep these here the same way.

http://codereview.appspot.com/144071/diff/1/2#oldcode841
Line 841: <t hangText="opensocial_app_url">Required. The URL of the
application
agreed

http://codereview.appspot.com/144071/diff/1/2#oldcode845
Line 845: <t hangText="opensocial_instance_id">Optional. An opaque
identifier
agreed. See notes in the OpenSocial specification on views.
I think we keep this whole section. We grandfather in the names (e.g.
keep "opensocial" prefix). owner_id is optional for gadgets, but in the
OS spec described as required.

For gadgets - we can describe the owner is the user who went through the
process of subscribing to the gadget or placing the gadget on their
page. The viewer would be the current logged in user or the reserved
word "guest" for someone not logged in.

For OS we would keep the more precise wordings.

BTW - We have gadgets where the owner is either irrelevant or implicit,
and at times the viewer is more important.

http://codereview.appspot.com/144071/diff/1/2
File draft/Gadgets-API-Specification.xml (right):

http://codereview.appspot.com/144071/diff/1/2#newcode71
Line 71: capabilities like a rich set of social APIs.</t>
OK

http://codereview.appspot.com/144071/diff/1/2#newcode864
Line 864:
https://[container-hostname]/[application-name]/certificates/xoauth_public_keyvalue
See my notes on the OpenSocial spec, in a similar section.

http://codereview.appspot.com/144071/diff/1/3
File draft/OpenSocial-Specification.xml (right):

http://codereview.appspot.com/144071/diff/1/3#newcode512
Line 512: <section title="Public Key Location">
I like the absence of <application>, just worried changing it might look
like "breaking" backwards compatibility. Of course the value is only
"recommended".

It could be worded like, "The recommended name is <the one w/o
application>. Some containers may wish to support <the one with
application> as well for compatibility with versions of the
specification prior to 1.0.

http://codereview.appspot.com/144071/diff/1/3#newcode517
Line 517: <section title="gadgets.views.ViewType"
I can put them back along with the words:
"The following are some values that may be supported by the application.
Should the application support them, they must be implemented as
follows."
This will provide some common language between different applications.

http://codereview.appspot.com/144071

[Lane LiaBraaten]

Hi Jon,

So are you still planning to modify OpenSocial-Specification.xml in this patch?  If we keep sign owner/viewer, and the views stuff in the gadgets spec, then I'm not sure there's anything to add to the OS-Spec. I bring it up because I'm not sure the OS-Spec.xml will be the right place for this content after we get done shuffling things around.  Not a big deal, but wanted to mention it.

A few comments inline...

-Lane

On Wed, Nov 4, 2009 at 4:49 PM, <jon.we...@gmail.com> wrote:

http://codereview.appspot.com/144071/diff/1/2
File draft/Gadgets-API-Specification.xml (left):

http://codereview.appspot.com/144071/diff/1/2#oldcode574
Line 574: <t>sign_owner: gadgets.io.RequestParameters.SIGN_OWNER
(default 'true')</t>

See the comment in the OpenSocial specification on the Views. We can
keep these here the same way.

Yep - looks good

http://codereview.appspot.com/144071/diff/1/2#oldcode841
Line 841: <t hangText="opensocial_app_url">Required. The URL of the
application

agreed

http://codereview.appspot.com/144071/diff/1/2#oldcode845
Line 845: <t hangText="opensocial_instance_id">Optional. An opaque
identifier

agreed. See notes in the OpenSocial specification on views.
I think we keep this whole section. We grandfather in the names (e.g.
keep "opensocial" prefix). owner_id is optional for gadgets, but in the
OS spec described as required.

For gadgets - we can describe the owner is the user who went through the
process of subscribing to the gadget or placing the gadget on their
page. The viewer would be the current logged in user or the reserved
word "guest" for someone not logged in.

For OS we would keep the more precise wordings.

BTW - We have gadgets where the owner is either irrelevant or implicit,
and at times the viewer is more important.

I think the container should have some leeway in defining what "OWNER" means based on context.  Take Friend Connect for example...there the owner is "the site" (not a user) - so if you ask for the owner's name you'll get "My Guitar Site".  So I think it's fine if you've got a case where OWNER is not really a user (or available at all).
 

http://codereview.appspot.com/144071/diff/1/2
File draft/Gadgets-API-Specification.xml (right):

http://codereview.appspot.com/144071/diff/1/2#newcode71
Line 71: capabilities like a rich set of social APIs.</t>

OK

http://codereview.appspot.com/144071/diff/1/2#newcode864
Line 864:
https://[container-hostname]/[application-name]/certificates/xoauth_public_keyvalue

See my notes on the OpenSocial spec, in a similar section.

http://codereview.appspot.com/144071/diff/1/3
File draft/OpenSocial-Specification.xml (right):

http://codereview.appspot.com/144071/diff/1/3#newcode512
Line 512: <section title="Public Key Location">

I like the absence of <application>, just worried changing it might look
like "breaking" backwards compatibility. Of course the value is only
"recommended".

It could be worded like, "The recommended name is <the one w/o
application>. Some containers may wish to support <the one with
application> as well for compatibility with versions of the
specification prior to 1.0.

A developer is probably going to find this URL somewhere in the site's documentation, so I don't think it's too important to standardize (hence the "recommended"). Also since it's just recommended, a container using the existing URL format doesn't even need to change anything (and if they want to, they can just host the key in both URLs).

Since it's just a recommendation, I'd prefer less text, but I don't feel strongly either way.
 

http://codereview.appspot.com/144071/diff/1/3#newcode517
Line 517: <section title="gadgets.views.ViewType"

I can put them back along with the words:
"The following are some values that may be supported by the application.
Should the application support them, they must be implemented as
follows."
This will provide some common language between different applications.

sounds good

http://codereview.appspot.com/144071

[Jon]

I'm going to take another pass at it based on the input received. A
spot in the OS-Spec may still be required, we'll see.