activity-api.xml

<?xml version="1.0" encoding="US-ASCII"?>
<?xml-stylesheet type='text/xsl' href='./rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="exp" docName="activity-api-01" ipr="full3978">
  <front>
    <title abbrev="ActivityStreamsAPI">Activity Streams API Draft
    Specification 0.1</title>

    <author fullname="Monica Wilkinson" initials="M." surname="Wilkinson">
      <organization>VMWare</organization>
    </author>

    <date day="16" month="June" year="2011" />

    <abstract>
      <t>The Activity Streams API Specification is designed to make it easy
      for developers transmit and receive activities about a subject in a
      secure and platform agnostic fashion.</t>

      <t>The focus on simplicity and legibility has driven us to model this
      API as a <xref target="REST"></xref> endpoint which emits a <xref
      target="JSON"></xref> response.</t>
    </abstract>

    <note title="Requirements Language">
      <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
      "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
      document are to be interpreted as described in RFC 2119.</t>
    </note>
  </front>

  <middle>
    <section title="Introduction">
      <t>This specification describes how to model, transmit, receive and
      parse activities using a simple, secure, generic <xref
      target="REST"></xref> endpoint. Activities are modeled according to the
      concepts defined in Section 3 of <xref
      target="Activity_Streams_1_0"></xref></t>

      <t>Before you get started, we recommend you review the Activity Stream API Sample Response in <xref
      target="Example"></xref> at the end of the specification which is self
      descriptive.</t>
    </section>

    <section title="Activity Workflow">
      <t>The very first step is to find the Activity Streams endpoint if it is
      not known by the calling code.</t><t>The next step is to see if the
      endpoint points to all public data or also has private data.
      If the endpoint contains private data, the Service Provider will return an
      authorization challenge as described in OAuth 2.0, and the Consumer must
      then guide the user through an appropriate authorization flow to obtain
      the credentials necessary to access this private data. Upon successful
      authorization, the Consumer may request data from the Activity Streams
      endpoint using these authorization credentials. Whether accessing public
      or private data, Consumers may request a specific subset of the user's
      data using standard Query Parameters. Upon a successful request, the
      data is returned in the response, and the Consumer may then parse the
      response data and use it as desired.</t>

      <t>If the Consumer wishes to maintain an synchronized copy of the data or
      get new activities as soon as they are available. They should subscribe
      to the resource as defined in <xref target="PubSubHubbub_0_4">
      the PubSubHubub specification (Draft 0.4)</xref></t>

      <t>The following sections detail each of these steps.</t>

      <section title="Discovery">
        <t>Providers who support this specification SHOULD establish their
        conformance by making the Activity Stream API endpoint discoverable
        from the root of the domain using LRDD. 
        
        TODO: Define whether webfinger will be involved or just an LRDD processor.

        <figure title="Sample discovery via LRDD/JRD Non Normative">
          <artwork>
  GET /.well-known/lrdd?format=json&amp;uri=http%3A%2F%2Fbestsite.com%2Fwilly9
  HTTP/1.1
  Host: bestsite.com
              
  -------------------------------------------------------

  HTTP/1.1 200 OK
  Content-Type: application/json
  Content-Lenght: 100

  {
    "openid": {"url" : "http://www.bestsite.com/openid"},
    "stream_get_json" : {"template": "http://www.bestsite.com/{uri}/stream"},
    ...
  }
        </artwork>
        </figure></t>
        <t>
      This allows for Consumers wishing to access a user's Activity Stream to
      start with an Initial Identifier such as the domain name of the Service
      Provider's web site, for example: "bestsite.com".
      Consumers can then perform Discovery on the Initial Identifier canonicalized
      to determine where the Activity Streams endpoint for this Service Provider
      resides. If successful, the Consumer may then attempt to request information
      from that endpoint. </t>
      </section>

      <section title="Retrieval of Activities">
        <t>All content fetching requests to the Service Provider are made as
        HTTP GET operations on a URL deriving form the base URL described in
        section 2.1. Consumers MAY append additional path information and/or
        query string parameters to the Base URL as part of the request, as
        specified in section X.X [TODO] Additionally, authentication
        information MUST be sent using OAuth 2.0 Protocol as defined in <xref
        target="OAuth_2_0"></xref> for protected resources. For details on
        declaring the end point as a protected resource see section 6 of <xref
        target="OAuth_2_0"></xref></t>

        <figure title="Invoking the stream endpoint">
          <artwork>
  GET /willy9/stream HTTP /1.1
  Host: bestsite.com
  Accept: application/json
  Accept-Language: en-us,en;q=0.5


  -------------------------------------------------------

  HTTP/1.1 200 OK
  Content-Type: application/json
  Date: Mon, 17 May 2010 03:49:19 GMT
  Content-Lenght: 400

  {
    "id": "http://www.bestsite.com/willy9/stream",
    "lang" : "en-US",
    "title" : "Willy Wonka's Activity Stream on The Best Site",
    ...
    "items" :[..]
  }

        </artwork>
        </figure>
      </section>

      <section title="Authentication and Authorization">
        <t>The activities returned from the Activity Stream endpoint MAY
        contain a mix of public and private data. If Service Providers wish to
        make some response data publicly available and also provide additional
        info given the proper authorization credentials, they SHOULD provide a
        200 OK response to requests without authorization with a
        WWW-Authenticate header in the response indicating that additional
        info may be available via the specified authorization mechanisms.</t>

        <t>In this example below the endpoint can return public data invoked
        using HTTP but if the Consumer has the appropriate credentials for the
        user then it can also include private activities</t>

        <figure title="Example: Endpoint returning partial set"><artwork>
     HTTP/1.1 200 OK
     WWW-Authenticate: Token realm='Service', error='token_missing'

      {
        "id": "http://www.bestsite.com/willy9/stream",
        "lang" : "en-US",
        "title" : "Willy Wonka's Activity Stream on The Best Site",
        ...
        "items" :[..]
      }
        </artwork></figure>
        <t>If no access is possible without authorization then a 401 HTTP status
        code and the WWW-Authenticate header will be sent in the response with
        an empty body as described in section 6.1 of <xref target="OAuth_2_0">OAuth 2.0</xref>
        </t>
      </section>

      <section title="Synchronization">
        <t>In order to keep the data synchronized it is possible to invoke
        repeatedly the Activity Streams endpoint using GET and passing
        if-modified-since headers. This concept is known as polling and it is
        not considered the most efficient for keeping multiple repositories of
        data in sync. The Activity Streams endpoint SHOULD support
        subscriptions so consumers can receive near real time updates without
        much expense using <xref target="PubSubHubbub_0_4"></xref></t>
      </section>

      <section title="Creation of Activities">
        <t>This section describes how to publish activities by an external
        generator on behalf of the user on a given Service Provider. All
        content creation requests to the Service Provider are made as HTTP
        POST operations on the base URL described in section 2.1.
        Additionally, authentication information MUST be sent using OAuth 2.0
        Protocol as defined in <xref target="OAuth_2_0"></xref>. For details
        on declaring the end point as a protected resource see section 6 of
        <xref target="OAuth_2_0"></xref></t>

        <t>The basic algorithm for creating activities is to use the dot product
        notation of the JSON properties as the POST parameters</t>

        <t>Example:</t>

        <t><list style="hanging">
            <t hangText="title (string)">Title or comment for the activity
            provided by the user</t>

            <t hangText="postedTime (string)">This can be specified for
            backdated activities.</t>

            <t hangText="object.displayName (string)">The display name for the
            object</t>
          </list></t>

        <t>The activity actor and generator are optional. If the Service
        Provider uses OAuth then this information can be obtained from the
        access token</t>
      </section>
    </section>

    <section title="Types">
      <t>The following sections define the different types that represent
      concepts from the activity streams data model in JSON.</t>

      <section title="Activity">
        <t>An Activity represents an activity as defined by link the Activity
        Streams specifications.</t>

        <t>An Activity has the following properties:</t>

        <t><list style="hanging">
            <t hangText="id (string)">A URI that serves as an identifier for
            this activity. If not present then the link will be used
            in its place. For the full definition see Section 3.1.1 of <xref
            target="Activity_Streams_1_0"></xref></t>

            <t hangText="streamFaviconUrl (string)">The URL of an icon
            represents this activity. This property MAY be <spanx
            style="verb">null</spanx> as defined in Section 3.1.2 of <xref
            target="Activity_Streams_1_0"></xref></t>

            <t hangText="postedTime (string)">The time that the activity
            occurred, as a W3CDTF timestamp as defined in Section 3.1.3 of
            <xref target="Activity_Streams_1_0"></xref></t>

            <t hangText="actor (Object)">The actor of this activity as defined
            in Section 3.1.4 of <xref
            target="Activity_Streams_1_0"></xref></t>

            <t hangText="verb (array&lt;string&gt;)">The list of verb URIs for
            this activity as defined in Section 3.1.5 of <xref
            target="Activity_Streams_1_0"></xref>If there is only a
            single verb then the name of the verb can be placed as the value
            for the "verb" property. Example: "verb" : "post"</t>

            <t hangText="object (Object)">The object of this activity as
            defined in Section 3.1.6 <xref
            target="Activity_Streams_1_0"></xref></t>

            <t hangText="target (Object)">The target of this activity as
            defined in Section 3.1.7 <xref
            target="Activity_Streams_1_0"></xref></t>

            <t hangText="generator (Object)">The application which created the
            activity as defined in Section 3.1.8 <xref
            target="Activity_Streams_1_0"></xref></t>

            <t hangText="title (string)">An HTML representation of the natural
            language title for this activity as defined in Section 3.1.10 of
            <xref target="Activity_Streams_1_0"></xref></t>

            <t hangText="body (string)">An HTML representation of a natural
            language describing this activity including visual elements such
            as thumbnails as defined in Section 3.1.11 of <xref
            target="Activity_Streams_1_0"></xref></t>

            <t hangText="privacy (array&lt;string&gt;)">An array of
            identifiers which describe how the consumer can deliver the
            updates as defined in Section 3.1.12 of <xref
            target="Activity_Streams_1_0"></xref></t>
          </list></t>

        <t>If additional properties are present in an Activity, they MUST be
        ignored.</t>
      </section>

      <section title="Object">
        <t>Object is the base type of objects that can be referenced by
        activities. Specific object types will extend this basic object with
        additional properties that are specific to the object type in
        question.</t>

        <t>Properties:</t>

        <t><list style="hanging">
            <t hangText="id (string)">Unique identifier for the object. If not
            present in the JSON response, assume it matches the name.
            For more details on the format for the id see Section 3.2.1 on
            <xref target="Activity_Streams_1_0"></xref></t>

            <t hangText="title (string)">Label for the object meant for human
            consumption. For more details on the title see Section 3.2.2
            on <xref target="Activity_Streams_1_0"></xref></t>

            <t hangText="summary (string)">Description or snippet of the
            object if this textual. For more details see Section 3.2.3 on
            <xref target="Activity_Streams_1_0"></xref></t>

            <t hangText="image (string)">Representative image as described in
            Section 3.2.4 of <xref
            target="Activity_Streams_1_0"></xref></t>

            <t hangText="permalinkUrl (string)">Link to human readable representation
            of the object. If the id is not present, then this field will be
            considered the id. For more details see Section 3.2.5 on <xref
            target="Activity_Streams_1_0"></xref></t>

            <t hangText="objectType (array&lt;string&gt;)"><xref
            target="Activity_Streams_1_0"></xref>An array of URIs
            which identify the object type. Example: "objectType" :
            [{"http://www.maps.com/schema/earth-aerial-photo", "photo"}] For
            more details see Section 3.2.6. If there is only one objectType
            the publisher CAN place the URI directly inside objectType and not
            use an array. Example: "objectType" : "photo"</t>

            <t hangText="postedTime (string)">W3CDTF timestamp representing the time
            when the object was created.</t>

            <t hangText="owner (Object)">An optional property used to specify the
            owner of the object if different than the actor of the activity.</t>

            <t hangText="inResponseTo (Object)">If this activity was done in
            response to another object then this is the location to syndicate
            the object.</t>

          <t hangText="actionLinks (array&lt;ActionLink&gt;)">This is a list of
          all the actions which can be performed on a given activity by humans.
          For more details see the <xref
            target="ActionLink">ActionLink definition</xref>.
          </t>

          <t hangText="likes (ReactionActivityStream)">
              This property is a list of all the likes
          which were done in response to this object. The object is implied
          to be the current object and the verb is "like".
          For more details see the <xref target="ReactionActivityStream">
          ReactionActivityStream definition</xref></t>

          <t hangText="comments (ReplyStream)">This property is a list of
          objects which were posted in reply to the current object such as
          comments on a photo and a count for more details see the <xref
            target="ReplyStream">ReplyStream definition</xref>. The reply does not have an inResponseTo
          property because its implied that its in-reply-to the parent object.</t>

          </list></t>


        </section>

      <section title="ActivityStream">
        <t>An activity stream is a collection of activities. Often these
        activities are related in some way, such as being by the same
        actor.</t>

        <t>An ActivityStream has the following properties:</t>

        <t><list style="hanging">
            <t hangText="title (string)">A human-readable name for this
            stream. This property MAY be <spanx style="verb">null</spanx> if
            the stream has no title or name.</t>

            <t hangText="lang">The language used to generate the summary and
            content sections of the activities.</t>

            <t hangText="items (array&lt;Activity&gt;)">The activities
            comprising this stream. This property MUST NOT be <spanx
            style="verb">null</spanx>. Items should be display in reverse
            chronological order.</t>

            <t hangText="id (string)">A URI that serves as an identifier for
            this activity stream. This property MUST NOT be <spanx
            style="verb">null</spanx>.</t>

            <t hangText="subject (object)">If this stream is considered to be
            about a specific object -- usually a Person -- the publisher
            SHOULD include the object representation for the subject. If
            included then only the minimal representation is necessary in
            subsequent references. Generally this is the actor of the
            activities.</t>
          </list></t>

      </section>

    <section title="ActionLink" anchor="ActionLink">
      <t>Properties of an ActionLink</t>

      <t><list style="hanging">
          <t hangText="title">Human readable text describing the action.
          Example: "Share with boingy.com !""</t>

          <t hangText="url (string)">URL to the human readable page
          where the end user can engage in the action</t>
        </list></t>
    </section>


    <section title="ReactionActivityStream" anchor="ReactionActivityStream">
    <t>The Reaction Activity construct is the same as an Activity construct
    but without an object property.</t>

    <t><list style="hanging">
        <t hangText="count">The total number of activities which were done
        in response.</t>
        <t hangText="items (array &lt;Activity&gt;)">An array of Activities
        without any objects.</t>
    </list></t>
    </section>

    <section title="ReplyStream" anchor="ReplyStream">

    <t><list style="hanging">
        <t hangText="count">The total number of replies</t>
        <t hangText="items (array &lt;Object&gt;)">This array does not need
        to include all the replies but MAY include a subset of replies.</t>
    </list></t>
    </section>

    </section>

        <section anchor="ActivityStream.JSON-C" title="JSON-C Compatibility">
          <t>For an Activity Stream API, the activity stream MUST be
          considered the <spanx style="verb">data</spanx> element in <xref
          target="JSON-C"></xref>. Several of the properties above follow the
          JSON-C style guide. In addition there are several other properties
          which publishers CAN use to provide additional information</t>

          <t><list style="hanging">
              <t hangText="Link Properties">selfLink, nextLink, previousLink,
              editLink</t>

              <t hangText="Paging Properties">currentItemCount, itemsPerPage,
              startIndex, totalItems, pagingLinkTemplate,pageIndex,
              totalPages</t>

              <t hangText="Errors">If you wish to report errors then your
              Activity Stream API response should include an encompassing
              object</t>
            </list></t>

          <t>JSON-C properties which are not recommended to be used in an
          Activity Stream API are: updated, deleted and kind</t>
        </section>
        
    <section anchor="Example" title="Activity Stream API Sample Response">
      <figure>
        <preamble>Here is a (non-normative) example of what a response from
        the API could look like. Note that the <xref target="JSON"></xref>
        format follows the <xref target="Portable_Contacts"></xref> address
        element schema as defined in Section 7.4</preamble>

        <artwork><![CDATA[
{
	"id": "http://www.bestsite.com/willy9/stream",
	"lang" : "en-US",
	"title" : "Willy Wonka's Activity Stream on The Best Site",
	"subject" :
	{
		"id": "http://bestsite.com/user/608201527",
		"name" : "Willy Wonka",
		"image" : "http://www.bestsite.com/willy9/picture",
		"permalinkUrl" : "http://www.bestsite.com/willy9",
		"objectType": ["http://activitystrea.ms/schema/1.0/person"]
	},
	"generator" :
	{
		"permalinkUrl" : "http://www.bestsite.com",
		"name" : "The Best Site"
	},
	"items": 
	[{
		"id": "http://bestsite.com/activity/608201527_118700288155735",
		"permalinkUrl" : "http://www.bestsite.com/608201527/posts/118700288155735",
		"postedTime": "2010-04-27T06:02:36+0000", 
		"title" : "Willy Wonka just RSVPed for Mozilla Labs Night - April 2010",
		"actor" : { "id": "http://bestsite.com/user/608201527"},
		"verb" : ["rsvp-yes"],
		"object" : 
		{
			"id": "http://www.meetup.com/Mozilla-Labs-Meetup/calendar/13194973/",
			"name" : "Mozilla Labs Meetup (Mountain View, CA)",
			"permalinkUrl" : "http://www.meetup.com/Mozilla-Labs-Meetup/calendar/13194973/i3/site",
			"objectType": "event",
			"dtStart" : "2010-04-29T06:02:00+0000",
			"location" : {
				"id": "http://www.mozilla.org/locations/mtv",
				"name" : "Mozilla Office in Mountain View, CA",
				"streetAddress": "650 Castro St",
				"locality" : "Mountain View",
				"region": "CA",
				"country" : "US"
			}
		},
		"serviceProvider" :
		{
			"permalinkUrl" : "http://www.meetup.com",
			"name" : "Meetup",
			"icon" : "http://photos-b.ak.fbcdn.net/photos-ak-sf2p/v43/97/2403839689/app_2_2403839689_2546.gif"
		}
	},
	{
		"id": "http://bestsite.com/activity/608201527_118700288155740",
		"permalinkUrl" : "http://www.bestsite.com/608201527/posts/118700288155740",
		"postedTime": "2010-04-25T06:02:36+0000", 
		"title" : "Willy Wonka uploaded a photo to the Incredible Shots album on Flickr",
		"actor" : { "id": "http://bestsite.com/user/608201527"},
		"verb" : ["http://activitystrea.ms/schema/1.0/post"],
		"object" :
		{
			"name" : "Burning Tree",
			"permalinkUrl" : "http://www.flickr.com/willy/photo/29382938293",
			"objectType": ["http://activitystrea.ms/schema/1.0/photo"],
			"thumbnail" : {url: "http://www.flickr.com/willy/photo/29382938293/small.jpg"},
			"fullImage" : {url: "http://www.flickr.com/willy/photo/29382938293/large.jpg"}
		},
		"target" : 
		{
			"permalinkUrl" : "http://www.flickr.com/willy/album/2323232",
			"name" : "Incredible Shots",		
			"thumbnail" : {url: "http://www.flickr.com/willy/photo/29382938293/small.jpg"},
			"objectType": ["http://activitystrea.ms/schema/1.0/photo-album"]
		},
		"serviceProvider" :
		{
			"permalinkUrl" : "http://www.flickr.com",
			"name" : "Flickr",
			"icon" : "http://www.flickr.com/favicon.ico"
		}
	}]
}
]]></artwork>

        <postamble>Note that we do not need to keep detailing the actor
        properties because they were already presented in the subject. Also
        note that the "id" is optional. When the "id" is not present we assume
        the value of "permalinkUrl" can be used instead</postamble>
      </figure>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <reference anchor="JSONSchema"
                 target="http://tools.ietf.org/html/draft-zyp-json-schema-03">
        <front>
          <title>JSON Schema Draft 03</title>
		<author fullname="Kris Zyp" initials="K." surname="Zyp">
	      <organization>SitePen</organization>
	    </author>
        </front>
      </reference>

      <reference anchor="JSON-C"
                 target="http://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.html">
        <front>
          <title>JSON-C Style Guide</title>
        </front>
      </reference>

      <reference anchor="REST"
                 target="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm">
        <front>
          <title>Representational State Transfer (REST)</title>
        </front>
      </reference>

      <reference anchor="JSON"
                 target="http://tools.ietf.org/id/draft-crockford-jsonorg-json-04.txt">
        <front>
          <title>JavaScript Object Notation (JSON)</title>
		<author fullname="David Crockford" initials="D." surname="Crockford">
	      <organization>JSON.org</organization>
	    </author>
        </front>
      </reference>

      <reference anchor="XRD_1_0"
                 target="http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html">
        <front>
          <title>Extensible Resource Descriptor (XRD) Version Committee Draft
          02</title>
        </front>
      </reference>

      <reference anchor="Activity_Streams_1_0"
                 target="http://activitystrea.ms/specs/json/1.0/">

		<front>
          <title>JSON Activity Streams 1.0</title>
	     	<author fullname="James M Snell" initials="J.M." surname="Snell">
		      <organization>IBM</organization>
		    </author>

		    <author fullname="Martin Atkins" initials="M." surname="Atkins">
		      <organization>SAY Media</organization>
		    </author>

		    <author fullname="Will Norris" initials="W." surname="Norris">
		      <organization>Google</organization>
		    </author>

		    <author fullname="Chris Messina" initials="C." surname="Messina">
		      <organization>Citizen Agency, Google</organization>
		    </author>

		    <author fullname="Monica Wilkinson" initials="M." surname="Wilkinson">
		      <organization>MySpace, Facebook, Socialcast</organization>
		    </author>

		    <author fullname="Rob Dolin" initials="R." surname="Dolin">
		      <organization>Microsoft</organization>
		    </author>
        </front>
      </reference>

      <reference anchor="Portable_Contacts"
                 target="http://www.portablecontacts.net/draft-spec.html">
        <front>
          <title>Portable Contacts 1.0 Draft C</title>
		<author fullname="Joseph Smarr" initials="J." surname="Smarr">
	      <organization>Plaxo</organization>
	    </author>
        </front>
      </reference>

      <reference anchor="OAuth_2_0"
                 target="http://tools.ietf.org/html/draft-ietf-oauth-v2-16">
        <front>
          <title>OAuth 2.0 Protocol (Draft 16)</title>
        </front>
      </reference>

      <reference anchor="PubSubHubbub_0_4">
        <front>
          <title>PubSubHubbub Protocol 0.4 (draft)</title>
        </front>
      </reference>
    </references>
  </back>
</rfc>