Socialwg/Social API/Connections API

From W3C Wiki

(Work in progress)

Based on http://www-10.lotus.com/ldd/lcwiki.nsf/xpAPIViewer.xsp?lookupName=IBM+Connections+5.0+API+Documentation#action=openDocument&res_title=IBM_Connections_APIs_ic50&content=apicontent

Overview of IBM's Connections 5.0 API

The IBM Connections Social Platform deals with a range of components.

  • Activities (this is not the Activity Streams idea of an Activity. In Connections, an "Activity" is a type of workflow-oriented forum. The term pre-dates Activity Streams)
  • Blogs
  • Bookmarks
  • Communities
  • Files
  • Forums
  • "Ideation Blog"
  • Metrics
  • Profiles
  • Profile Administration
  • Related Communities
  • Search APIs
  • News Repository
  • Wikis

Notes

Authentication

The Connections APIs support Basic and OAuth 2.0 based authentication [1]

Format

The Connections API is based primarily on the Atom Syndication Format, Atom Publishing Protocol, and makes extensive use of Connections-specific extensions.

Discovery

Connections uses a "Follow your nose" discovery model 

  GET /activities/serviceconfigs HTTP/1.1
  Authorization: Basic xx
  Host: enterprise.example.com:9080
  Accept: */*

<?xml version="1.0" encoding="UTF-8"?>

<feed xmlns="http://www.w3.org/2005/Atom">
  <title type="text">IBM Connections Service Configurations</title>
  <generator 
   xmlns:snx="http://www.ibm.com/xmlns/prod/sn" 
   uri="http://www.ibm.com/xmlns/prod/sn" 
   version="3.0.0.0" 
   snx:buildLabel="20100712.0035">
      IBM Connections - Configuration
  </generator>
  <updated>2010-07-13T17:37:47.759Z</updated>
  <author>
    <name>IBM Connections Administrator</name>
  </author>

  <id>urn:lsid:ibm.com:config:serviceconfigs:com.ibm.lc.f018651a-ab95-4c31-b3e3-0f99e7ebc116</id>
  <category term="email-exposed" scheme="http://www.ibm.com/xmlns/prod/sn/configuration"></category>
  <link 
   href="http://enterprise.example.com/activities/serviceconfigs/" 
   rel="self" 
   type="application/atom+xml">
  </link>

  <entry>
    <category term="service-config" scheme="http://www.ibm.com/xmlns/prod/sn/type"></category>
    <title type="text">help</title>
    <id>urn:lsid:ibm.com:config:help:com.ibm.lc.f018651a-ab95-4c31-b3e3-0f99e7ebc116</id>
    <link href="http://enterprise.example.com/help" rel="alternate" type="text/html"></link>
    <link 
     href="https://enterprise.example.com/help" 
     rel="http://www.ibm.com/xmlns/prod/sn/alternate-ssl" 
     type="text/html">
    </link>
    <updated>2010-07-13T17:37:47.759Z</updated>
  </entry>
  <entry>
    <category term="service-config" scheme="http://www.ibm.com/xmlns/prod/sn/type"></category>
    <title type="text">mobile</title>
    <id>urn:lsid:ibm.com:config:mobile:com.ibm.lc.f018651a-ab95-4c31-b3e3-0f99e7ebc116</id>
    <link href="http://enterprise.example.com/mobile" rel="alternate" type="text/html"></link>
    <link 
     href="https://enterprise.example.com/mobile" 
     rel="http://www.ibm.com/xmlns/prod/sn/alternate-ssl" 
     type="text/html">
    </link>
    <updated>2010-07-13T17:37:47.759Z</updated>
  </entry>

  <entry>
    <category term="service-config" scheme="http://www.ibm.com/xmlns/prod/sn/type"></category>
    <title type="text">wikis</title>
    <id>urn:lsid:ibm.com:config:wikis:com.ibm.lc.f018651a-ab95-4c31-b3e3-0f99e7ebc116</id>
    <link href="http://enterprise.example.com/wikis" rel="alternate" type="text/html"></link>
    <link 
     href="https://enterprise.example.com/wikis" 
     rel="http://www.ibm.com/xmlns/prod/sn/alternate-ssl" 
     type="text/html">
    </link>
    <updated>2010-07-13T17:37:47.759Z</updated>
  </entry>
  <!-- ... -->
</feed>

Following

Following is considered to be part of the "common" functionality across connections. The following objects can be followed:

  • Activities - You can follow any public activity. To follow a private activity, you must be a member of the activity.
<host_server>/activities/follow/atom/service
  • Blogs - You can follow any stand-alone blog; you cannot follow community blogs.
<host_server>/blogs/follow/atom/service
  • Communities - You do not have to be a member to follow public or moderated communities. You must be a member to follow private communities.
<host_server>/communities/follow/atom/service
  • Files - You can follow any public file or file folders. You can only follow private files and file folders that have been shared with you.
<host_server>/files/follow/atom/service
  • Forums - You can follow any public forum or forum topic. You can only follow private forums if you are a member or owner of the forum.
<host_server>/forums/follow/atom/service
  • News repository - You can follow any tag.
<host_server>/news/follow/atom/service
  • Profiles - You can follow any profile.
<host_server>/profiles/follow/atom/service
  • Wikis - You can follow any public wiki or wiki page. You must be a reader, editor, or owner of a private wiki before you can follow it or one of its pages.
<host_server>/wikis/follow/atom/service

Getting a feed of the followed resource

  • A feed of all the resources being followed
GET /{source}/follow/atom/resources?source={source}
  • (for OAuth requests) A feed of all the resources being followed.
GET /{source}/follow/oauth/atom/resources?source={source}

To start following a resource, POST an Atom entry to. 

POST /{source}/follow/atom/resources?source={source}
<?xml version="1.0" encoding="UTF-8"?>
<entry 
 xmlns="http://www.w3.org/2005/Atom" 
 xmlns:app="http://www.w3.org/2007/app" 
 xmlns:snx="http://www.ibm.com/xmlns/prod/sn">
  <category term="resource-follow" scheme="http://www.ibm.com/xmlns/prod/sn/type"/>
  <category term="activities" scheme="http://www.ibm.com/xmlns/prod/sn/source" />
  <category term="activity" scheme="http://www.ibm.com/xmlns/prod/sn/resource-type" />
  <category term="60eac668-ab21-4795-b112-51eeaf54ffaa" scheme="http://www.ibm.com/xmlns/prod/sn/resource-id" />
</entry>

"to stop following something, you must first find the resource that you want to stop following in the following feed. From the Following service document for the application, retrieve the web address of the collection from its href attribute. Send a GET request to that web address to retrieve the Following feed"

"To stop following a resource, find its rel="edit" link and send a DELETE request to the web address specified in its href attribute."

Common Types

There are some common object types used throughout connections including:

  • Bookmarks [2]
  • Member entries [3]
  • Tags Category Documents [4]
  • Follow entry [5]
  • Report entry [6]
  • Moderation action entry [7]

Common Tasks

There are some common tasks used throughout connections including [8] :

  • Creating/Retrieving/Updating bookmarks
  • Retrieving members
  • Updating members
  • Removing members

Common Query String Parameters

Common Query String Parameters [9]

Activities

Note: this is NOT Activity Streams. The Connections Activities component is a workflow-oriented forum that predates Activity Streams

act_Nav_201.gif

HTTP GET

Get the Service Document 

/activities/service/atom2/service

My Activities Feed 

/activities/service/atom2/activities

Completed Activities Feed 

/activities/service/atom2/completed

All Activities Feed 

/activities/service/atom2/everything

Todo Feed 

/activities/service/atom2/todos

Tags Category Document 

/activities/service/atom2/tags

Get a Specific Activity 

/activities/service/atom2/activitynode

HTTP POST

Create activities by POSTing an Atom entry (without template: [10], with template: [11] ) 

/activities/service/atom2/activities

Create a post within an Activity by POSTing an Atom entry to the Activities Feed (without template: [12], with template: [13]) 

/activities/service/atom2/activity

HTTP PUT

Update a specific Activity 

/activities/service/atom2/activitynode

HTTP DELETE

Delete a specific Activity 

/activities/service/atom2/activitynode

Delete's are "Soft Deletes". A deleted entry can be restored. [14]

Retrieved from "https://www.w3.org/wiki/index.php?title=Socialwg/Social_API/Connections_API&oldid=79507"