[Proposal for 1.0] Deprecate redundant opensocial.* methods

[Lane LiaBraaten]

The osapi.* API makes many opensocial.* methods unnecessary. Deprecating the opensocial.* methods will decrease the size of the OpenSocial APIs and encourage developers to use the osapi.*, which was designed to be lightweight and easier to use. However, there is not a complete overlap, so we can't just deprecate opensocial.* altogether.

The proposal is:

1. move the entire opensocial.* API reference to it's own spec file
2. label any objects and functions that can be replaced by osapi.* as DEPRECATED. These methods will still be available in opensocial-1.0, but deprecating them now will allow use to remove them in a future version.

For a listing of what objects and methods will be kept and which will be deprecated, see: http://wiki.opensocial.org/index.php?title=Deprecate_redundant_opensocial.*_methods


-Lane

[Chris Chabot]

Would it be entirely to radical to move the remaining opensocial.* functions to the osapi name space?

I agree it would be a bit of a change, but a reduction in top level name spaces will help to prevent confusion (is it osapi.foo or opensocial.foo or gadgets.foo?) and with 'osapi' standing for the OpenSocial API, well it's not like osapi.hasPermission(etc) would be such a odd function naming scheme.

[Paul Lindner]

I'm a little squeamish here,  osapi.* have some issues of their own (for example spec problems with osapi.http) that make them unsuitable for current deployments.

I'm willing to move forward only if we can get osapi.* rock solid and if we have migration doc showing each opensocial.* call with the equivalent osapi.* call(s).

[Bess Ho]

It would be nice to have a table to track these APIs.

Finish reviewing & editing MySpace Developer Book few months ago. I highly suggest OS spec team to keep good documentation on comparing previous version. What if OS developers have to work on a legacy OS app in older version? This will save a lot of unnecessary time in debugging and upgrading.

--
Bess Ho

[Mark W.]

A quick question, and if if this is a tangent, then please pardon the
interruption--I'll buy you all a round next time I see you to make up
for it.....

First, I think the real issue that Lane has identified is that we have
two programming models in the spec; opensocial and osapi. The right
thing to do is have one consistent, clean, "rock solid" way of doing
things. From Paul's post, it doesn't sould like we are there yet.

It also seems like this is a flavor of the problem that Lane, myself,
and others are trying to address with extensions. We have something
that's really good, that we want people to use, but it's just not
quite there yet. What if we said that for 1.0, opensocial.* is the
programing model, but we are incubating osapi.* for 1.1?

This would do a couple of things:
First, it would give us the clean, consistent programming model that
we want. Whatever we choose for 1.0 we're going to live with for
awhile. If we really don't want to live with opensocial.* then we
should reconsider the timeline for 1.0 and figure out how to get osapi
rock solid.

Second, it would enable us to solidify the osapi.* APIs. 1.1 is on the
horizon for 2Q10. This should be plenty of time to reach the level of
maturity we require.

Third, since this will be incubating, it's implied that there's some
stability in what's there now and is moderately safe to use.

Again, I'm just thinking out loud...

-Mark W.

On Sep 23, 5:46 pm, Paul Lindner <lind...@inuus.com> wrote:
> I'm a little squeamish here,  osapi.* have some issues of their own (for
> example spec problems with osapi.http) that make them unsuitable for current
> deployments.
> I'm willing to move forward only if we can get osapi.* rock solid and if we
> have migration doc showing each opensocial.* call with
> the equivalent osapi.* call(s).
>

> On Wed, Sep 23, 2009 at 2:40 PM, Chris Chabot <chab...@google.com> wrote:
> > Would it be entirely to radical to move the remaining opensocial.*
> > functions to the osapi name space?
>
> > I agree it would be a bit of a change, but a reduction in top level name
> > spaces will help to prevent confusion (is it osapi.foo or opensocial.foo or
> > gadgets.foo?) and with 'osapi' standing for the OpenSocial API, well it's
> > not like osapi.hasPermission(etc) would be such a odd function naming
> > scheme.
>

> > On Wed, Sep 23, 2009 at 11:23 PM, Lane LiaBraaten <lliab...@google.com>wrote:
>
> >> The osapi.* API makes many opensocial.* methods unnecessary. Deprecating
> >> the opensocial.* methods will decrease the size of the OpenSocial APIs and
> >> encourage developers to use the osapi.*, which was designed to be
> >> lightweight and easier to use. However, there is not a complete overlap, so
> >> we can't just deprecate opensocial.* altogether.
>
> >> The proposal is:
>

> >>    1. move the entire opensocial.* API reference to it's own spec file
> >>    2. label any objects and functions that can be replaced by osapi.* as

> >>    DEPRECATED. These methods will still be available in opensocial-1.0, but
> >>    deprecating them now will allow use to remove them in a future version.
>
> >> For a listing of what objects and methods will be kept and which will be
> >> deprecated, see:

> >>http://wiki.opensocial.org/index.php?title=Deprecate_redundant_openso...
>
> >> -Lane
>
>

[Lane LiaBraaten]

On 9/23/09, Paul Lindner <lin...@inuus.com> wrote:
> I'm a little squeamish here, osapi.* have some issues of their own (for
> example spec problems with osapi.http) that make them unsuitable for current
> deployments.

Are your concerns all related to inconsistencies or vagueness in the
spec? If so, this is the time to fix them. If not, can you give more
details on the

> I'm willing to move forward only if we can get osapi.* rock solid and if we
> have migration doc showing each opensocial.* call with
> the equivalent osapi.* call(s).

Good idea. Who is your intended audience? App developers looking to
update their apps, or spec implementers looking to understand osapi?

Either way I think this doc would live outside the spec (on
wiki.opensocial.org), right?

-Lane

>
>
> On Wed, Sep 23, 2009 at 2:40 PM, Chris Chabot <cha...@google.com> wrote:
>
>> Would it be entirely to radical to move the remaining opensocial.*
>> functions to the osapi name space?
>>
>> I agree it would be a bit of a change, but a reduction in top level name
>> spaces will help to prevent confusion (is it osapi.foo or opensocial.foo
>> or
>> gadgets.foo?) and with 'osapi' standing for the OpenSocial API, well it's
>> not like osapi.hasPermission(etc) would be such a odd function naming
>> scheme.
>>
>>
>> On Wed, Sep 23, 2009 at 11:23 PM, Lane LiaBraaten
>> <llia...@google.com>wrote:
>>
>>> The osapi.* API makes many opensocial.* methods unnecessary. Deprecating
>>> the opensocial.* methods will decrease the size of the OpenSocial APIs
>>> and
>>> encourage developers to use the osapi.*, which was designed to be
>>> lightweight and easier to use. However, there is not a complete overlap,
>>> so
>>> we can't just deprecate opensocial.* altogether.
>>>
>>> The proposal is:
>>>

>>> 1. move the entire opensocial.* API reference to it's own spec file
>>> 2. label any objects and functions that can be replaced by osapi.* as

[Paul Lindner]

On Thu, Sep 24, 2009 at 8:49 AM, Lane LiaBraaten <llia...@google.com> wrote:

On 9/23/09, Paul Lindner <lin...@inuus.com> wrote:
> I'm a little squeamish here,  osapi.* have some issues of their own (for
> example spec problems with osapi.http) that make them unsuitable for current
> deployments.

Are your concerns all related to inconsistencies or vagueness in the
spec?  If so, this is the time to fix them.  If not, can you give more
details on the

for example, the spec says:

   osapi.http("http://example.com/", {param: value}) 

when instead you need to use this syntax:

   osapi.http({href: "http://example.com/", param: value});

 

> I'm willing to move forward only if we can get osapi.* rock solid and if we
> have migration doc showing each opensocial.* call with
> the equivalent osapi.* call(s).

Good idea.  Who is your intended audience?  App developers looking to
update their apps, or spec implementers looking to understand osapi?

I'd like to see migration aids in the deprecation notice.  i.e.

 @deprecated(since="1.0")

 @see "osapi.http"

  Deprecated since 1.0.  Use osapi.http to make your proxied calls.etc..

[Lane LiaBraaten]

On Thu, Sep 24, 2009 at 3:25 PM, Paul Lindner <lin...@inuus.com> wrote:

On Thu, Sep 24, 2009 at 8:49 AM, Lane LiaBraaten <llia...@google.com> wrote:

On 9/23/09, Paul Lindner <lin...@inuus.com> wrote:
> I'm a little squeamish here,  osapi.* have some issues of their own (for
> example spec problems with osapi.http) that make them unsuitable for current
> deployments.

Are your concerns all related to inconsistencies or vagueness in the
spec?  If so, this is the time to fix them.  If not, can you give more
details on the

for example, the spec says:

   osapi.http("http://example.com/", {param: value}) 

when instead you need to use this syntax:

   osapi.http({href: "http://example.com/", param: value});

osapi.* is intended to be 1:1 with the RPC endpoints, but there isn't an equivalent RPC endpoint for osapi.http.  Nonetheless, all other osapi.* methods take a single parameter, a JSON object, so osapi.http should follow suit.

This is already how it is implemented in Shindig, and I'm not aware of any other live implementations, so the effect on existing gadgets will be nil (and the effect on app developers will be less confusion).

Any other concerns with osapi.* ?

 

> I'm willing to move forward only if we can get osapi.* rock solid and if we
> have migration doc showing each opensocial.* call with
> the equivalent osapi.* call(s).

Good idea.  Who is your intended audience?  App developers looking to
update their apps, or spec implementers looking to understand osapi?

I'd like to see migration aids in the deprecation notice.  i.e.

 @deprecated(since="1.0")

 @see "osapi.http"

  Deprecated since 1.0.  Use osapi.http to make your proxied calls.etc..

Sounds reasonable to me.

-Lane

[Lane LiaBraaten]

On Wed, Sep 23, 2009 at 2:40 PM, Chris Chabot <cha...@google.com> wrote:

Would it be entirely to radical to move the remaining opensocial.* functions to the osapi name space?

I think it's too radical, only because osapi.* is a 1:1 mapping with RPC endpoints, and there are no equivalents for the remaining opensocial.* methods. 

The gadgets.* namespace may be a better fit. 

What about deprecating the permissions stuff - is that actually used/useful?

-Lane

[Paul Lindner]

On Fri, Sep 25, 2009 at 9:47 AM, Lane LiaBraaten <llia...@google.com> wrote:

for example, the spec says:

   osapi.http("http://example.com/", {param: value}) 

when instead you need to use this syntax:

   osapi.http({href: "http://example.com/", param: value});

osapi.* is intended to be 1:1 with the RPC endpoints, but there isn't an equivalent RPC endpoint for osapi.http.  Nonetheless, all other osapi.* methods take a single parameter, a JSON object, so osapi.http should follow suit.

This is already how it is implemented in Shindig, and I'm not aware of any other live implementations, so the effect on existing gadgets will be nil (and the effect on app developers will be less confusion).

Any other concerns with osapi.* ?

I just read the spec again, it appears that osapi.http is the only offender, the rest appears fine.  Can we get an osapi compliance gadget?  (or is that already in the 0.9 compliance gadget?)

[Evan Gilbert]

osapi.http is a replacement for gadgets.io.makeRequest() which we are not proposing to deprecate. So I don't think this impacts deprecating opensocial.*.

+1 to this proposal

As an aside - what is the list of opensocial.* methods that can't be deprecated? Many of these may be unused in active implementations, and I'm fine deprecating these and asking for containers to define new extensions if they want to support the functionality (for example, we can add an osapix.permissions.get()).

Evan

[Lane LiaBraaten]

From: http://wiki.opensocial.org/index.php?title=Deprecate_redundant_opensocial.*_methods

Methods with no osapi equivalent:

opensocial

• opensocial.getEnvironment
• opensocial.hasPermission
• opensocial.newNavigationParameters
• opensocial.requestPermission
• opensocial.requestShareApp

opensocial.Environment

• getDomain
• supportsField

opensocial.NavigationParameters

• getField
• setField

opensocial.Permission

-Lane

[Chris Chabot]

Do we feel these would fit well under the gadgets.* namespace?

[Lane]

Ideally we'd have a service for supportsField stuff, in which case it
could end up as osapi.foo.supportsField. At this point, however, I
don't think it makes sense to change it.

I think we can deprecate opensocial.hasPermission, and
opensocial.requestPermission.

That leaves requestShareApp and the navigation parameters stuff (which
are used as parameters to requestShareApp [1]). I don't think that
really fits in the gadgets.* namesspace because (1)sharing the app
with another person is social, and (2) I'm not sure where to put it
(e.g. gadgets.util.requestShareApp). Anyone have suggestions on what
to do with request shareApp?

-Lane

BTW - I'm looking for an owner on this proposal. I'm signed up for a
couple other proposals that will also require lots of spec formatting,
so I could use a hand on this one.

[1] http://wiki.opensocial.org/index.php?title=Opensocial.NavigationParameters_%28v0.9%29

On Sep 26, 2:15 am, Chris Chabot <chab...@google.com> wrote:
> Do we feel these would fit well under the gadgets.* namespace?
>

> On Fri, Sep 25, 2009 at 7:59 PM, Lane LiaBraaten <lliab...@google.com>wrote:

>
> > From:
> >http://wiki.opensocial.org/index.php?title=Deprecate_redundant_openso...
>
> > Methods with no osapi equivalent:
>
> > opensocial
>

> >    - opensocial.getEnvironment
> >    - opensocial.hasPermission
> >    - opensocial.newNavigationParameters
> >    - opensocial.requestPermission
> >    - opensocial.requestShareApp
>
> > opensocial.Environment
>
> >    - getDomain
> >    - supportsField
>
> > opensocial.NavigationParameters
>
> >    - getField
> >    - setField

>
> > opensocial.Permission
> > -Lane
>
> > On Fri, Sep 25, 2009 at 10:46 AM, Evan Gilbert <uid...@google.com> wrote:
>
> >> osapi.http is a replacement for gadgets.io.makeRequest() which we are not
> >> proposing to deprecate. So I don't think this impacts deprecating
> >> opensocial.*.
> >> +1 to this proposal
>
> >> As an aside - what is the list of opensocial.* methods that can't be
> >> deprecated? Many of these may be unused in active implementations, and I'm
> >> fine deprecating these and asking for containers to define new extensions if
> >> they want to support the functionality (for example, we can add an
> >> osapix.permissions.get()).
>
> >> Evan
>

> >> On Fri, Sep 25, 2009 at 10:41 AM, Paul Lindner <lind...@inuus.com> wrote: