API Changes

[Andreas Kohn <an...@gmail.com>]

Hi,

I'm finally back to work a bit on shindig, but before submitting review
requests I think it would be nice to know which kind of API changes are
acceptable :)

I have essentially 3 pending parts:

1. Change the MediaItems request parameters to match opensocial: currently
shindig expects the media item id in the 'mediaItemId' parameter, but
OpenSocial says it should be in the 'id' parameter instead. This change
would break the *RPC* API, the REST API would be unaffected. It could be
made to be compatible though by checking both parameter names.

2. Change the MediaItems (and others) 'tags' field from 'String' to
'Array<String>'. This change again is coming from the OpenSocial standard,
but as it affects return values in the Java API getting it to be compatible
seems hard, if not impossible.

3. Make it possible to inject a factory for CollectionOptions, which would
allow us to implement additional parameter handling without having to
replace both handler code and service interfaces. This is a change purely
on the Java API, a user would not be affected in any way.

Any advice would be appreciated :)

Regards,
--
Andreas

Re: API Changes

[Ryan Baxter <rb...@gmail.com>]

There are some compliance tests
https://svn.apache.org/repos/asf/shindig/trunk/content/gadgets/compliance/
https://svn.apache.org/repos/asf/shindig/trunk/content/gadgets/compliance-1.0/
but I have never run them, I am sure they are out of date.

On Thu, Feb 13, 2014 at 11:55 AM, Stanton Sievers <ss...@apache.org> wrote:
> I think in general we need to update our compliance tests to help avoid
> issues like this in the future.
>
> Does anyone know of any tools that can help to do this?  I'm wondering how
> other projects that are tied to a spec handle spec compliance.
>
> -Stanton
>
>
> On Thu, Feb 13, 2014 at 11:14 AM, Andreas Kohn <an...@gmail.com>wrote:
>
>> Hi,
>>
>> On Wed, Feb 12, 2014 at 7:18 PM, Ryan Baxter <rb...@apache.org> wrote:
>>
>> > On Tue, Feb 11, 2014 at 12:57 PM, Andreas Kohn <an...@gmail.com>
>> > wrote:
>> > > 1. Change the MediaItems request parameters to match opensocial:
>> > currently
>> > > shindig expects the media item id in the 'mediaItemId' parameter, but
>> > > OpenSocial says it should be in the 'id' parameter instead. This change
>> > > would break the *RPC* API, the REST API would be unaffected. It could
>> be
>> > > made to be compatible though by checking both parameter names.
>> >
>>
>>
>> > I like the solution of support both, and I am fine with that.  Would
>> > the MediaItem interface change?
>>
>>
>> No, it only changes the names of the parameters expected in the RPC calls
>> (it actually affects two,
>> but both can be made to be handled backwards-compatibly.)
>>
>> Working on finalizing the parts 1 and 3, hopefully should have some code to
>> show tomorrow or Monday. Keeping the change
>> for 2 locally is fine for me, as long as we can get those incompatibilities
>> between the OpenSocial standard
>> and Shindig out eventually.
>>
>> Regards,
>> --
>> Andreas
>>

Re: API Changes

[Stanton Sievers <ss...@apache.org>]

I think in general we need to update our compliance tests to help avoid
issues like this in the future.

Does anyone know of any tools that can help to do this?  I'm wondering how
other projects that are tied to a spec handle spec compliance.

-Stanton


On Thu, Feb 13, 2014 at 11:14 AM, Andreas Kohn <an...@gmail.com>wrote:

> Hi,
>
> On Wed, Feb 12, 2014 at 7:18 PM, Ryan Baxter <rb...@apache.org> wrote:
>
> > On Tue, Feb 11, 2014 at 12:57 PM, Andreas Kohn <an...@gmail.com>
> > wrote:
> > > 1. Change the MediaItems request parameters to match opensocial:
> > currently
> > > shindig expects the media item id in the 'mediaItemId' parameter, but
> > > OpenSocial says it should be in the 'id' parameter instead. This change
> > > would break the *RPC* API, the REST API would be unaffected. It could
> be
> > > made to be compatible though by checking both parameter names.
> >
>
>
> > I like the solution of support both, and I am fine with that.  Would
> > the MediaItem interface change?
>
>
> No, it only changes the names of the parameters expected in the RPC calls
> (it actually affects two,
> but both can be made to be handled backwards-compatibly.)
>
> Working on finalizing the parts 1 and 3, hopefully should have some code to
> show tomorrow or Monday. Keeping the change
> for 2 locally is fine for me, as long as we can get those incompatibilities
> between the OpenSocial standard
> and Shindig out eventually.
>
> Regards,
> --
> Andreas
>

Re: API Changes

[Andreas Kohn <an...@gmail.com>]

Hi,

On Wed, Feb 12, 2014 at 7:18 PM, Ryan Baxter <rb...@apache.org> wrote:

> On Tue, Feb 11, 2014 at 12:57 PM, Andreas Kohn <an...@gmail.com>
> wrote:
> > 1. Change the MediaItems request parameters to match opensocial:
> currently
> > shindig expects the media item id in the 'mediaItemId' parameter, but
> > OpenSocial says it should be in the 'id' parameter instead. This change
> > would break the *RPC* API, the REST API would be unaffected. It could be
> > made to be compatible though by checking both parameter names.
>


> I like the solution of support both, and I am fine with that.  Would
> the MediaItem interface change?


No, it only changes the names of the parameters expected in the RPC calls
(it actually affects two,
but both can be made to be handled backwards-compatibly.)

Working on finalizing the parts 1 and 3, hopefully should have some code to
show tomorrow or Monday. Keeping the change
for 2 locally is fine for me, as long as we can get those incompatibilities
between the OpenSocial standard
and Shindig out eventually.

Regards,
--
Andreas

Re: API Changes

[Ryan Baxter <rb...@apache.org>]

Hi Andreas, welcome back ;)  My answers are below, but from a release
perspective I think we want to get a 2.5.1 out the door and then we
can start on 3.0, which would allow some API changes.

On Tue, Feb 11, 2014 at 12:57 PM, Andreas Kohn <an...@gmail.com> wrote:
> Hi,
>
> I'm finally back to work a bit on shindig, but before submitting review
> requests I think it would be nice to know which kind of API changes are
> acceptable :)
>
> I have essentially 3 pending parts:
>
> 1. Change the MediaItems request parameters to match opensocial: currently
> shindig expects the media item id in the 'mediaItemId' parameter, but
> OpenSocial says it should be in the 'id' parameter instead. This change
> would break the *RPC* API, the REST API would be unaffected. It could be
> made to be compatible though by checking both parameter names.
I like the solution of support both, and I am fine with that.  Would
the MediaItem interface change?  This would be something I would not
want to happen in 2.5.1.
>
> 2. Change the MediaItems (and others) 'tags' field from 'String' to
> 'Array<String>'. This change again is coming from the OpenSocial standard,
> but as it affects return values in the Java API getting it to be compatible
> seems hard, if not impossible.
Yeah agree this seems like it would change the interfaces.
>
> 3. Make it possible to inject a factory for CollectionOptions, which would
> allow us to implement additional parameter handling without having to
> replace both handler code and service interfaces. This is a change purely
> on the Java API, a user would not be affected in any way.
>
This seems OK to me based on your description.  Sounds like you would
just be changing the underlying implementations.
> Any advice would be appreciated :)
>
> Regards,
> --
> Andreas