[OS 3] A proposal for standardised syndication of Gadgets

[Niels van Dijk]

Hi all,

OpenSocial has 'write once, deploy anywhere' as its mantra. Many platform feature a 'gadget store' where locally configured gadgets can be picked by users. However, sharing or syndicating gadgets in between application platforms or portals is in most cases very cumbersome and often involves the copy-pasting of lengthy URLs that contain references to a Gadget XML. This is a bad both for usability as well as for automated discovery of (remote) gadgets. The latter would e.g. allow portal admins to automatically aggregate gadgets collections from multiple trusted remote parties.

This document proposes a profile to standardise the way Gadget syndication can be achieved. It builds on top of well the well know ATOM syndication standard [1] and optionally allows for digitally signing the syndication feed to allow for trustworthy exchange of Gadget definitions.

This proposal was inspired by the "Gadgets Subscriptions" feature as it is found in the Atlassian products Jira and Confluence [2].

I welcome your comments and remarks,

Cheers,
Niels




Gadget Syndication ATOM Profile (GSAP)
The key words "MUST", "MUST NOT", etc are to be interpreted as described in RFC2119 [3]

* To allow for Gadget syndication a container, portal or some other registry MUST make available a GSAP compliant ATOM [1] feed.

* GSAP MUST adhere to rfc4287 [1]

* The GSAP endpoint SHOULD implement https

* The GSAP endpoint MAY implement XML signing. If XML signing is implemented the entire document MUST be signed.

* GSAP features the following required elements:
The following ATOM Constructs MUST be made available in a GSAP feed metadata (http://tools.ietf.org/html/rfc4287#section-4.1.1):
title        - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.14
link         - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.7
author    - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.1
id            - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.6
icon        - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.5
updated - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.13

The feed MUST contain at least 1 entry element (http://tools.ietf.org/html/rfc4287#section-4.1.2) which MUST contain the following ATOM Constructs:
title           - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.14
link            - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.7
id               - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.6
updated    - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.13
summary   - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.13

* GSAP features support the following optional elements:
The following elements MAY be made available as part of the feed:
rights      - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.10
source    - defined as in http://tools.ietf.org/html/rfc4287#section-4.2.11

* Example of the above
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Gadget library published from https://wiki.surfnetlabs.nl</title>
  <link rel="base" href="https://wiki.surfnetlabs.nl" />
  <author>
    <name>Confluence</name>
  </author>
  <id>https://wiki.surfnetlabs.nl/rest/gadgets/1.0/g/feed</id>
  <icon>https://wiki.surfnetlabs.nl/s/1911/6/2/_/download/resources/com.atlassian.gadgets.publisher:ajs-gadgets/images/icons/confluence.png</icon>
  <updated>2012-02-15T20:06:20Z</updated>
  <entry>
    <title>Gadget spec at https://wiki.surfnetlabs.nl/rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:gadget-search/gadgets/gadget-search.xml</title>
    <link rel="alternate" href="https://wiki.surfnetlabs.nl/rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:gadget-search/gadgets/gadget-search.xml" />
    <id>https://wiki.surfnetlabs.nl/rest/gadgets/1.0/g/com.atlassian.confluence.plugins.gadgets:gadget-search/gadgets/gadget-search.xml</id>
    <updated>2012-02-15T20:06:11Z</updated>
    <summary>The Confluence search gadget  allows you to query a space for content with the keywords you provide</summary>
  </entry>
</feed>

* Using atom:content?
One point I was thinking about, but have not found a solution for is the use of atom:content. A GSAP feed MAY implement an content element containing the actual Gadget XML definition. This seems especially usefull in case the feed was signed, a it it then very clear what was signed. However, this will introduce a chunk of XML in an XML document which may cause problems.

References:
[1] http://tools.ietf.org/html/rfc4287
[2] http://confluence.atlassian.com/display/JIRA/Subscribing+to+Another+Application%27s+Gadgets
[3] http://www.ietf.org/rfc/rfc2119.txt

[Matthew Marum]

In OpenSocial 2.0, we deprecated support for ATOM throughout the spec.

While ATOM support could certainly be optional, could we also figure out what a JSON gadget catalog format would look like?

Matt Marum

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

[Henry Saputra]

Was the deprecation of ATOM format in incubation? If it is, the 2.5
and 3.0 would be the good time to make it permanent?

- Henry

[Matthew Marum]

Incubating sections are just for new proposals where we need to give them chance to evolve.   Incubating parts are tagged in green.   Deprecated parts of the spec are tagged in yellow boxes.   For deprecated pieces, we would be able to remove them in the next major version of the spec.  The earliest we could remove ATOM completely from the spec would be OpenSocial 3.0.

Matt

[Henry Saputra]

Uff thanks for clarifying it Matt.

- Henry

[Niels van Dijk]

Hi,

I think creating a JSON formatted version would be rather easy, but ATOM seems like the natural standard to use here. It was designed for syndication.
Additionally I really like the possibility of XML signing as it is possible in ATOM. What equivalent would there be if it were JSON?

Cheers,
Niels

[James M Snell]

Whether Atom fits here is dependent entirely on how we expect this to
be used. There needs to be a basic JSON-based API for managing the
catalog of gadgets available, that much should be clear. Whether we
mandate the publication of an Atom-feed detailing the gadgets
contained in the catalog depends on how we think that catalog is going
to be exposed to third parties. If the catalog is only going to be
visible within the context of the gadget container, then Atom is not
going to be necessary at all. If we want to allow the catalog to be
browsed by arbitrary third parties, Atom makes a lot of sense
(although we can also use the Activity Streams format for this as
well).

- James

On Fri, Feb 17, 2012 at 2:38 AM, Niels van Dijk

[Mark W.]

Niels,

I think this is an interesting idea, but I've got some questions. The first one is around OAuth. In many circumstances, an app is given, by the container, a key/secret that is used. Or more generally, there is a registration process with the "gadget store". I'm not sure where/how we'd account for this. Another thing is, and as much as it pains me to say this, the reality right now is that we don't have "write once run anywhere" apps. I think there are two reasons for this. 

The first is that each container still varies greatly in the implementation of opensocial. I think we are a lot better here in 2.0 but we need to get a lot better at this. 

The second is that each container still has it's own "stuff" that needs to be used to make a truly useful app. For example, Jive has discussions, blogs, documents, etc. that are not in the spec (yet, hopefully!). An app that does not take advantage of these is very limited in what it can do in the platform. 

While I like having a better way of discovering apps, I think we'll need to spend some concerted effort on portability before we have what we're looking for. 

[Niels van Dijk]

Hi James,

Thanks for you feedback.
I had not thought of the management side of things, and agree that there
a JSON version makes much more sense.

As for the 'publishing' of the catalog, I was indeed thinking about a
catalog that would be externally browsable. In that case a generic thing
like atom is more usefull as it does not require additoin programming to
display this in many applications, whereas JSON formatted data will
still need at minimum configuration.

Cheers,
Niels

[Niels van Dijk]

Hi Mark,

Some good questions, please find my comments inline

On 02/18/2012 12:12 AM, Mark W. wrote:
> Niels,
>
> I think this is an interesting idea, but I've got some questions. The
> first one is around OAuth. In many circumstances, an app is given, by
> the container, a key/secret that is used. Or more generally, there is
> a registration process with the "gadget store". I'm not sure where/how
> we'd account for this. Another thing is, and as much as it pains me to
> say this, the reality right now is that we don't have "write once run
> anywhere" apps. I think there are two reasons for this.

The OAuth things is clearly an issue to get some gadgets working. As the
oAuth stuff is hardcoded in a gadget in stead of configurable via e.g.
settings this cannot be solved right now. That is however no reason to
not offer a catalog for gadgets that do not rely on container config.

>
> The first is that each container still varies greatly in the
> implementation of opensocial. I think we are a lot better here in 2.0
> but we need to get a lot better at this.
>
> The second is that each container still has it's own "stuff" that
> needs to be used to make a truly useful app. For example, Jive has
> discussions, blogs, documents, etc. that are not in the spec (yet,
> hopefully!). An app that does not take advantage of these is very
> limited in what it can do in the platform.

Firstly, although I see what you mean it seems a bit silly to me to
worry about implementations that do not follow the OpenSocial spec when
desining the spec. I feel we should assume that we add something like
this catalog to the spec we may assume the rest of the (required parts
of) the spec are also implemented. Second, a catalog as I proposed also
has merit for containers that have their own extentions of OpenSocial as
this at least allows discovery in a standerdized way between these
containers of the same 'brand' and version. In the Jive case it could be
2 customers that choose to share gadgets. When at some point in the
future a version of the spec does have more features that will ceate
better interop for gadgets, but that does not seem like a reason for me
to not introduce a useful feature now.

What your point makes clear for me most of al is that the catalog should
*not* have OpenSocial specific stuff but be as generic as possible, and
should have a representation for the OS version + extensions it is able
to work with, much like one can already declare in the moduleprefs of a
gadget.

>
> While I like having a better way of discovering apps, I think we'll
> need to spend some concerted effort on portability before we have what
> we're looking for.

I am shure that this is not the best setup. However it is a very basic
one that is able to serve at least two concrete usecases, of which one (
the Atlassian version) is already working code. It is rather easy to
implement in general and as such will provide a good starting point for
further discussions into what we need for discovery.

Cheers,
Niels

> --
> You received this message because you are subscribed to the Google
> Groups "OpenSocial and Gadgets Specification Discussion" group.

> To view this discussion on the web visit
> https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/oNUY1g2WWhkJ.