divining the true nature of an activity

[David Primmer]

Most of these questions have to do with the Atom format, since there
are more rules regarding it's function. However, some of the questions
regarding what is actually stored in what fields applies to both json
and atom.

Now, with activities, we have the special situation where we have an
object that is quite similar to an Atom Entry with a source element
(it contains a streamUrl field which references the collection that it
came from). This has caused me to wonder if the URLs shouldn't be at
least as specified as they are in the REST spec.

Here's the sample entry activity from the spec:

<entry xmlns="http://www.w3.org/2005/Atom">
<category term="status"/>
<id>http://example.org/activities/example.org:87ead8dead6beef/self/af3778</id>
<title type="html">&lt;a href="foo"&gt;some activity&lt;/a&gt;</title>
<summary>Some details for some activity</summary>
<updated>2008-02-20T23:35:37.266Z</updated>
<link rel="self" type="application/atom+xml"
href="http://api.example.org/activity/feeds/.../af3778"/>
<author><uri>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</uri></author>
<content>
<activity xmlns="http://ns.opensocial.org/2008/opensocial">
<bodyId>383777272</bodyId>
<activity>
</content>
</entry>

1 Question about the use of {guid} in resource urls: Should it have to
include the prefix "example.org"? Is it possible that the prefix comes
from the containerId in the social token? If not, then what is the
containerId doing there? Is there a case where the native storage
format in the container for the example above would be
"87ead8dead6beef" and the {guid} portion of the request url does not
include "example.org:"?

From section 2, data representations, looks like the containerid is
embedded in the guid userid in the spec :

"atom:entry/atom:id aliases the "id" field. The JSON format id is the
OpenSocial globally unique ID, which consists of the container domain
(e.g., example.org), a colon, and an alphanumeric string but with the
container domain prepended. For example, example.org:78gh37261ddfdf.
In the Atom format, it is translated into the required URI data type
by prepending "urn:guid:" to the OpenSocial ID string. These rules
are intended to make mapping IDs between the RESTful API and the JS
API straightforward while preserving global uniqueness."

2 What is entry/category doing in here? I don't see the field it's
hoisted from in the spec. Seems like an Atom-only idea.

3 entry/id: why is this a URL? It is confusing to end users if it is
similar to the self link or edit link. Shouldn't it be a URN?
something like urn:guid:example.org:/activities/example.org:87ead8dead6beef/@self/af3778
?

4 The link@self element seems to be intentionally a non-opensocial
spec url? Or is it another example of a possible spec-compliant url
space construction? In any case, it just raises questions. This
element hoists activity/url and so I think it should have the actual
open social link.

5 The source element is missing and cannot be matched with a feed element.

6 The generator element is missing and no clue what an appid might look like.

7 The http operation that produced this output is not indicated.

8 The actual feed context is absent so the interaction of the source
element and the feed element are not apparent. Also, the relation of
the request url and the ids and links are not apparent, and in the
collection example, the required feed/id element is missing.

My feeling about this is that the activity example needs an entire
Feed Document example representation to show implementers how the Feed
URL relates to the Feed ID and the Source ID field and to the Entry ID
value and even to the Entry self link.

In these examples, the "OpenSocial globally unique ID" for the
Activity is af3778.

Here's a corrected version that tries to address these questions:

Note, I've duplicated the elements in the entry/source element with
their counterparts in the feed element. This is not required per Atom
spec but is here as an example. Normally, when creating entry/source,
all non-entry elements in the feed would be copied to the source
element in the entry. http://atompub.org/rfc4287.html#element.source

Collection of activities generated by given user
GET /people/example.org:87ead8dead6beef/@self

<feed xmlns="http://www.w3.org/2005/Atom"
xmlos:osearch="http://a9.com/-/spec/opensearch/1.1">
<id>http://api.example.org/activities/example.org:87ead8dead6beef/@self</id>
<title>Collection of activities generated by jane.doe</title>
<updated>2008-02-20T23:35:37.266Z</updated>
<author><uri>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</uri></author>
<link rel="next"
href="http://api.example.org/activities/example.org:87ead8dead6beef/@self...(opensearch
pagination params)" />
<osearch:totalResults>100</osearch:totalResults>
<osearch:startIndex>1</osearch:startIndex>
<osearch:itemsPerPage>10</osearch:itemsPerPage>
<entry xmlns="http://www.w3.org/2005/Atom">
<id>urn:guid:example.org:/activities/example.org:87ead8dead6beef/@self/af3778</id>
<title type="html">&lt;i&gt;some activity&lt;/i&gt;</title>
<summary>Some details for some activity</summary>
<updated>2008-02-20T23:35:37.266Z</updated>
<link rel="self" type="application/atom+xml"
href="http://api.example.org/activities/example.org:87ead8dead6beef/@self/af3778"/>
<author><uri>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</uri></author>
<content>
<activity xmlns="http://ns.opensocial.org/2008/opensocial">
<bodyId>383777272</bodyId>
<activity>
</content>
<generator uri="http://example.org/gadgethosting/gadget12345.xml"/>
<source>
<id>http://api.example.org/activities/example.org:87ead8dead6beef/@self</id>
<title>Collection of activities generated by jane.doe</title>
<updated>2008-02-20T23:35:37.266Z</updated>
</source>
</entry>
</feed>

Two things I'm unsure of:

feed/id and source:id = the definitive collection url of the entry, in
this case, the @self collection. The issue of whether to make it a URL
or not is decided here and I haven't seen examples of where the
collection id is not a URL address. Also, it's hoisted from streamUrl
in the spec into entry/source but not feed/id.

source:title = The description of the collection personalized with the
resource name? In other words, how is STREAM_TITLE (A string
specifying the title of the stream.) determined programatically?

davep

[David Primmer]

duh! I re-read my post and found an error. this should be
GET /activities/example.org:87ead8dead6beef/@self

[Louis Ryan]

Some questions...

1.  Why is the URN for an activity typed by the inclusion of /activity

<id>urn:guid:example.org:/activities/example.org:87ead8dead6beef/@self/af3778</id>
 

... but its is not typed for author?

<author><uri>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</uri></author>

are we making decision for implementers about the uniqueness of id's across types. I would assume it would be safest to not assume global uniqueness and include the type. Do we need to standardize the type names in the spec or are implementors free to use any path construct they see fit for their ids and consumers should not expect to infer type from the URN.

2. Are we trying to imply a construct in our URNs that provides for direct construction of URIs?

urn:guid:example.org:/activities/example.org:87ead8dead6beef/@self/af3778

Would seem to allow for this and might set a dangerous precendent. In general I would prefer a clear delineation between the format of the URNs and the self links in the samples at least so its clear to folks that they are not necessarily interchangeable e.g. urn:guid:example.org:activities:87ead8dead6beef/@self/af3778 (if we intend to include type in the standard) or urn:guid:example.org:/activities/87ead8dead6beef/@self/af3778 (if we intend not to include type)

3. Cant we use self links on the feed and make its id a URN not a URI? Same applies to source.

4. source isnt necessary unless this feed is an aggregate as opposed to the owning container??

[David Primmer]

On Thu, Jun 26, 2008 at 9:35 AM, Louis Ryan <lr...@google.com> wrote:
> Some questions...
>
> 1. Why is the URN for an activity typed by the inclusion of /activity
>
> <id>urn:guid:example.org:/activities/example.org:87ead8dead6beef/@self/af3778</id>

just an oversight on my part when i created it from the url of the entry.

<id>urn:guid:example.org:activities:87ead8dead6beef/@self/af3778</id>

I think the general advice I've read is to keep your URNs as different
looking enough from the URL so that there's no temptation to try to
infer a connection. I think this is what you're getting at in #2.

>
> ... but its is not typed for author?
> <author><uri>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</uri></author>
>
> are we making decision for implementers about the uniqueness of id's across
> types. I would assume it would be safest to not assume global uniqueness and
> include the type. Do we need to standardize the type names in the spec or
> are implementors free to use any path construct they see fit for their ids
> and consumers should not expect to infer type from the URN.
>
> 2. Are we trying to imply a construct in our URNs that provides for direct
> construction of URIs?
> urn:guid:example.org:/activities/example.org:87ead8dead6beef/@self/af3778
> Would seem to allow for this and might set a dangerous precendent. In
> general I would prefer a clear delineation between the format of the URNs
> and the self links in the samples at least so its clear to folks that they
> are not necessarily interchangeable e.g.
> urn:guid:example.org:activities:87ead8dead6beef/@self/af3778 (if we intend
> to include type in the standard) or
> urn:guid:example.org:/activities/87ead8dead6beef/@self/af3778 (if we intend
> not to include type)
>
> 3. Cant we use self links on the feed and make its id a URN not a URI? Same
> applies to source.

As I said, I've not seen this in my travels, and all the spec examples
use URLs, but it certainly is within spec. From rfc4287 4.1.1:

"atom:feed elements MUST contain exactly one atom:id element.
atom:feed elements SHOULD contain one atom:link element with a rel
attribute value of "self". This is the preferred URI for retrieving
Atom Feed Documents representing this Atom feed."

One of the issues of consistency here is, as the Atom Spec says, "When
an Atom Document is relocated, migrated, syndicated, republished,
exported, or imported, the content of its atom:id element MUST NOT
change. Put another way, an atom:id element pertains to all
instantiations of a particular Atom entry or feed; revisions retain
the same content in their atom:id elements. It is suggested that the
atom:id element be stored along with the associated resource."

This is kinda tough to do dynamically generated for feeds/collections
if they're based off the URL configuration of the server, which could
change. This is why implementers should be creating a means to
permanently store the resource identifiers in the server and not have
it just be a function of the URL design.

>
> 4. source isnt necessary unless this feed is an aggregate as opposed to the
> owning container??

The first part of this question, up to aggregate makes sense to me and
the answer is that source elements are not mandatory, as part of the
original feed as they contain copies of feed elements. But once a feed
is broken apart during aggregation, the source elements MAY be built
and included in the entry. Originating servers can make this process
easier, and the feeds more bloated, by pre-generating the source
elements. The way we've done it in Shindig to this point does produce
source elements. I did this because the spec explicitly says to hoist
activity/streamUrl to the source/link@rel="self" element.

davep