Deploying IBM Lotus Connections: Application programming interface

Part 7 in our series on deploying IBM Lotus Connections covers working with the Lotus Connections APIs. This article is intended for I/T specialists and developers and is helpful when building programs that use Lotus Connections data and services.

Mac Guidera (mac_guidera@us.ibm.com), Senior I/T Specialist, IBM

Mac Guidera is a Senior I/T Specialist who has been with IBM Lotus since January 2006. He has been working on the IBM Software Services for Lotus Connections Early Adoption project since January 2007. Enjoy his blog on all things lotus at www.macguidera.net.



Frank Jania, Technical Evangelist, IBM

Frank Jania is currently the Technical Evangelist for IBM's Real Time Collaboration and Social Computing Technologies. He is responsible for building and maintaining relationships with business partners in an effort to enable them to use and extend IBM's collaboration platforms. In his almost eight years at IBM, Frank has developed tooling for the Sydney Olympic Web site, been the project lead for IBM Community Tools, done user interface work for IBM Research, and managed a distributed team of software engineers. A prolific inventor and member of IBM's IP community, Frank currently has 30 patents pending and is leading an effort to revitalize participation in the IP program across all of Software Group's Research Triangle Park site. Frank earned Bachelor and Master degrees in Electrical Engineering from The Cooper Union for the Advancement of Science and Art. Take a look at his social software blog.



FuYi Li (fuyi_li@us.ibm.com), Senior Software Engineer, IBM

FuYi Li is a Senior Software Engineer for IBM Lotus Connections working in Westford, MA. FuYi is the Lotus Connections Integration User Experience team lead working on linked values between Lotus Connections and existing applications such as IBM Lotus Sametime, IBM Lotus Notes, and IBM WebSphere Portal. FuYi architected and implemented the Lotus Connections portlet. FuYi holds an M.S. in Computer Science from Boston University and a B.S. in Computer Science from Beijing University of Aeronautics and Astronautics in Beijing, China.



Judy J. Piper (jjpiper@us.ibm.com), SDK Developer, IBM

Judy Piper is Staff Software Engineer at IBM and Lotus Connections Activities and Forums API Lead. She has great technical expertise in HTTP and XML and has extensive knowledge in web application development and social software in particular. As a Development Lab Advocate, Judy supports IBM business partners and customers in their product development and deployment. She has been a mentor and a project coach to teams of student co-op programmers and has managed many intern projects. She earned her B.S. in Computer Science from University of Utah and joined IBM in 2004.



11 September 2007

The IBM Lotus Connections API is provided to support requests for services from other programs that integrate Lotus Connections. The API provides interfaces to the five Lotus Connections features: Activities, Blogs, Communities, Dogear, and Profiles. Application programmers can use the API to build programs that use Lotus Connections data and services and to create programs that add new capabilities to the features Lotus Connections provides. Implementing the Lotus Connections API, developers can request information from Lotus Connections features. API and feed reader programs can also use the Atom syndication format to subscribe to various views of Lotus Connections data to keep informed of updates and new content. In addition, new content can be created and existing content can be modified with this API.

Each Lotus Connections feature has its own capabilities for editing and for syndication through the Atom updates and new APIs. In the sections that follow, we highlight the capabilities and structure for working with the component data and processes.

For more information about the APIs available in Lotus Connections, refer to the

Lotus Connections Application Programming Interfaces V1.0.1 documentation

posted on DeveloperWorks.

Reading from Activities

Activities APIs support read and write access to Activities content. The read APIs return an Atom feed. The write APIs publish, edit, or delete Activities content using the Atom Publishing Protocol (APP).

To retrieve a feed from Activities, you need to send an HTTP GET command on the feed URL as shown in listing 1.

Listing 1. HTTP GET command
GET /atomFeedPath HTTP/1.1
Host: hostname
Content-Type: application/atom+xml
Content-Length: nnn

Tables 1-4 show various collection and feed URLs and optional query parameters that you can use to filter the feed content. Table 1 lists collections and feeds that are available to the current authenticated user. You can find the full list of collections and feeds in the Atom Service document.

Tables 1-4 contain Activities query parameters and their descriptions.

Table 1. Service endpoints
Service pathReturned feedMeaningParameter
/activities Activities
overview
Returns a feed that contains a list of Activities that are accessible by the authenticated user.- Activities Query
Parameters
- Activities Common
Query Parameters
/completedCompletedReturns a feed that contains the authenticated user's Activities that are marked completed.- Activities Common
Query Parameters
/everythingEverythingReturns a feed that contains both Activities and entries that are accessible by the authenticated user.
See "Activities Common Query Parameters" for the list of available parameters.
- Activities Common Query Parameters
URL is found in Service DocumentTrashReturns a list of previously trashed content that is accessible by the authenticated user.- Activities Common Query Parameters
/todos To Do's Returns a list of To Do entries accessible by the authenticated user.- To Dos specific
query parameters
- Activities Common Query Parameters
URL is found in Service DocumentAn activityAn activity is a collection of entries. - Activities Common Query Parameters
/activity/ threaded Threaded Implements Atom Threading Extension. Each threaded feed contains only the top-level entries for a specific Activity or the top-level responses for a specific entry. - Activities Common Query Parameters
URL is found in a specified Activity feedACL member listThe ACL member list is a collection that lists all the members of a specific Activity. Each member is represented as an entry document. - Activities Common Query Parameters
/ tagsOverview tag cloudReturns overview tag cloud when no parameters are specified.
Table 2. Activities common query parameters
ParameterValueMeaning
pageThe current page numberThe current page number.
psThe page sizeThe page size.
tagLimit the Activities to only those with this tagOnly a single tag is supported.
sortfieldsList of sortfields to sortbyNAME, CREATED, LASTMOD.
sortorderThe sort order0 (ascending), 1 (descending) - multiples separated by commas to match sortfields.
searchQuery stringSearches across title and description – OR.
casesensitiveYes, no Specifies if a search should be case-sensitive or not. tThe default is not case-sensitive.
nodetypeType of an entry being requestedActivity, comment, bookmark, todo, file, email, chat
Table 3. Activities query parameters
ParameterValueMeaning
deletedyes, no, onlyWhether or not to include deleted Activities/content
publicyes, no, onlyWhether or not to include public Activities/content
templatesyes, no, onlyWhether or not to include templates
Table 4. To Do's query parameters
ParameterValueMeaning
Assignedtoassignee email addressReturns only items assigned to a specified person.
completedyes, no, only Specifies whether or not completed to-do's should be returned.

Example: Retrieving a list of the authenticated user’s available Activities without the Public Activities

Activities Overview is a collection of a current authenticated user's available Activities (collections). Activities Overview feed (/atom/activities) contains a list of Activities that are accessible by the authenticated user. To retrieve a list of the authenticated user's available Activities without the Public Activities, send an HTTP GET request to your Activities server as follows. By appending the public=no parameter to the URL, no Public Activities are included in the returned feed. See listing 2.

Listing 2. HTTP GET request
GET /activities/service/atom/activities?public=no HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: nnn

The result of this request is shown in listing 3.

NOTE: The following feed has been abbreviated.

Listing 3. A feed that contains a list of the authenticated user’s Activities without the Public Activities
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
  xmlns:xhtml="http://www.w3.org/1999/xhtml">
  
  <generator uri="http://www.ibm.com/xmlns/prod/sn" version="1.0">
  Lotus Connections - Activities</generator>
	<id>http://connections.renovations.com/activities/service/atom/activities?page=
	1&public=no&ps=3</id>
	<title type="text">Frank Adams's Activity Dashboard</title>
	<updated>2007-07-17T19:02:38Z</updated> 
	<author>
	  <name>Frank Adams</name>
	  <email>FrankAdams@renovations.com</email>
	</author> 
	<link rel="self" href="http://connections.renovations.com/activities/
	service/atom/activities?
	page=1&public=no&ps=3"/>

   <entry>
   <id>urn:lsid:ibm.com:oa:C05GC0A8011E2542E81E5A7C5E2F11000004</id>
  <title type="text">Customer Tracking</title>
      <link rel="edit" type="application/atom+xml" href=
      "http://connections.renovations.com/
      activities/service/atom/activitynode?activityNodeUuid=
      C05GC0A8011E2542E81E5A7C5E2F11000004" />
    <updated>2007-07-17T19:02:38Z</updated>
  <published>2007-06-12T22:24:53Z</published>
   <author>
    <name>Frank Adams</name>
    <email>FrankAdams@renovations.com</email>
  </author>
  <contributor>
    <name>Frank Adams</name>
    <email>FrankAdams@renovations.com</email>    
  </contributor>
  <category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="activity" 
  label="Activity"/>
  <category scheme="http://www.ibm.com/xmlns/prod/sn/priority" term="3000" 
  label="High"/>
      <category term="events" />
      <category term="marketing" />
        <link rel="self" href="http://connections.renovations.com/activities/service/
        atom/activity?activityUuid=C05GC0A8011E2542E81E5A7C5E2F11000004&
        page=1&public=no&ps=3"/>
  <content type="text">This is where we are tracking all of our customers for the 
  upcoming event so we can determine the accounts that will receive complimentary 
  passes to the event.</content>
    </entry>
…. More Activities are listed as Atom Entries ….
</feed>

Use the code in listing 4 to get the Activities Overview tag cloud:

Listing 4. GET Activities Overview tag cloud
GET /activities/service/atom/tags HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: nnn

The result of this request is shown in listing 5.

Listing 5. A tag cloud of Overview collection is returned as an app:categories document
<?xml version="1.0" encoding="utf-8"?>
<app:categories xmlns:app="http://purl.org/atom/app#" 
    xmlns:snx="http://www.ibm.com/xmlns/prod/sn"
    xmlns="http://www.w3.org/2005/Atom"
    fixed="no"> 
    <category term="asia" snx:frequency="1" />
    <category term="competition" snx:frequency="2" />
    <category term="connections" snx:frequency="1" />
    <category term="customers" snx:frequency="2" />
    <category term="events" snx:frequency="1" />
    <category term="growth" snx:frequency="2" />
    <category term="invite" snx:frequency="1" />
    <category term="launch" snx:frequency="1" />
    <category term="lotus" snx:frequency="1" />
    <category term="marketing" snx:frequency="3" />
    <category term="networking" snx:frequency="1" />
    <category term="promotions" snx:frequency="1" />
    <category term="sales" snx:frequency="2" />
    <category term="salesteammeeting" snx:frequency="5" />
    <category term="social" snx:frequency="1" />
    <category term="tactics" snx:frequency="1" />
</app:categories>

Writing to Activities

You can create, modify, and delete Activity entries, using HTTP POST, PUT, and DELETE methods.

Create a new activity for your Activities Overview

The Overview is the collection of Activities for the authenticated user. Each activity is listed in the Overview feed as an entry document with link rel="edit". To create a new activity, you need to make an HTTP POST call to the Activities Overview collection URL:

http://connections.renovations.com/activities/service/atom/activities with the proper Atom entry (see table 1) . The example in listing 6 creates a new Activity by sending an HTTP
POST request on the Overview collection with an Atom entry representation as a request body.

Listing 6. POST a new activity
POST /activities/service/atom/activities HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 195
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version=”1.0” encoding=”utf-8”?>
<entry xmlns=”http://www.w3.org/2005/Atom”>   
<id>urn:lsid:ibm.com:oa:C05GC0A8011E2542E81E5A7C5E2F11000004</id>
<author>
 <name>Frank Adams</name><email>FrankAdams@renovations.com</email>
</author>
<title type=”text”>a sample activity</title>
<content type=”text”>a sample entry content</content>
<published>2007-07-12T16:46:06.265Z</published>
</entry>

Add a new entry to an activity

To create a new entry in an existing activity, make an HTTP POST call to the Activity collection URL. You can find the Activity collection URL in the entry for the activity in any of the actvity feeds. The API documentation for the “Activity Entry Elements” identifies where to find the collection URL and the edit URL for an activity. The example in listing 7 creates an entry in an activity with a title and content wrapped as an Atom entry.

Listing 7. POST a new message entry to an Activity
POST /activities/service/atom/activity?activityUuid=C05GC0A8011E2542E81E5A7C5E2F11000004
HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 208
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version=”1.0” encoding=”utf-8”?>
<entry xmlns=”http://www.w3.org/2005/Atom”>
<title type=”text”>test entry </title>   
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="message"/>
<author>
 <name>Frank Adams</name><email>FrankAdams@renovations.com</email>
</author>
<content type=”text”>a test entry in sample activity…</content>
<published>2007-06-12T17:05:36.421Z</published></entry>

Post a file to an activity

To post a file to an existing activity, make an HTTP POST call to the Activity collection. Upon a successful POST, the Activities server creates a Media Entry, the newly posted resource file and a Media Link Entry, and metadata about the newly posted resource file, and then returns the Media Link Entry with the location of the entry. The example in listing 8 posts an image file called Sample.jpg to an existing activity. In this case, the HTTP POST Content-Type is image/jpg.

Listing 8. POST a file entry to an activity
POST /activityCollectionURL HTTP/1.1 HTTP/1.1
Host: connections.renovations.com
Content-Type: image/JPEG
Slug: Sample Photo
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
Content-Length: nnn
...binary data for the image file called “Sample.jpg”...

Create a to do to an existing activity

To create a to do to an existing activity, make an HTTP POST call to the Activity collection URL

http://connections.renovations.com/activityCollectionURL
with the proper Atom entry. The example in listing 9 creates a to do in an existing activity. In this case, include category element with term="todo".

Listing 9. POSTing a to do entry
POST /activityCollectionURL
HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 444
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:snx="http://www.ibm.com/xmlns/prod/sn">
<title type="text">connections api doc</title>
<content type="text">write a connections api doc</content>
<published>2007-06-12T20:07:10.093Z</published>
<snx:assignedto>fadams@ renovations.com </snx:assignedto>
<snx:duedate>2007-06-15 04:07:10:EDT-0400</snx:duedate>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" 
term="todo">To Do</category>

Add a new member to an existing Activity member list

Each Activity has a corresponding ACL member list collection. You add a member to the collection by issuing an HTTP POST to the ACL collection with an Atom Entry representation of the new member as the request body. Specify a new member using the atom:contributor element as shown in listing 10.

Listing 10. Add a new member to an activity
POST /activityCollectionURL
HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 1408
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<id>urn:lsid:ibm.com:oa:C05GC0A8011E2542E81E5A7C5E2F11000004</id>
<author>
 <name>Frank Adams</name><email>FrankAdams@renovations.com</email>
</author>
<contributor>
<email>fadams@renovations.com </email>
<name>Frank Adams</name>
</contributor>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="person" />
<snx:role xmlns:snx="http://www.ibm.com/xmlns/prod/sn" component=
"http://www.ibm.com/xmlns/prod/sn/activities">member</snx:role>
<title type="text">Frank Adams</title>
</entry>

Update an existing activity entry

To update an existing activity entry, make an HTTP PUT call to the entry edit URL with the modified entry as a request body. See listing 11.

Listing 11. Updating an existing activity entry
PUT /activityEntryEditURL
HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 252
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title type="text">sample entry</title>
<id>urn:lsid:ibm.com:oa: C05GC0A8011E2542E81E5A7C5E2F11000004</id>
<link rel="edit" href="entryEditURL" 
type="application/atom+xml" />
<content type="text">This entry is updated with a new content. </content>
<published>2007-06-13T14:36:33.474Z</published>
<author><name> Frank Adams</name>
</author>
</entry>

On a successful PUT on the entry, the server returns an HTTP status code, 200.

HTTP /1.1 200 OK

Delete an existing entry

To delete an existing entry, send an HTTP DELETE request to the entry URL. See listing 12.

Listing 12. Remove an existing entry from an Activity
DELETE /entryEditURL
HTTP/1.1
Host: connections.renovations.com
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl

On a successful DELETE on the entry, the server returns the following HTTP status:

HTTP /1.1 200 OK


Create a response to a parent entry

To add a response to an existing parent entry with the title sample entry, add a threading extension to the responding entry before posting it to the sample activity. See listing 13.

Listing 13. Create a response to a parent entry
POST /activityCollectionURL HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 252
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" 
xmlns:thr="http://purl.org/syndication/thread/1.0">
<title type="text">Good luck with your new adventures</title>
<content type="text">And have a safe trip back home!</content>
<published>2007-07-16T19:27:21.227Z</published>
<thr:in-reply-to 
source="activityCollectionURL" 
href="parentEntryURLURL" 
ref="urn:lsid:ibm.com:oa:96FGC0A80221E5C54FA8D3BE4D1E1B00003A" 
type="application/atom+xml" />
</entry>

On a successful POST, the server returns the newly created entry as a response body and the entry URL in the HTTP Location response header.


Blogs

In this section, we show how to get the Atom feed from the blog service and how to programmatically create, update, and delete a blog entry.

Like the rest of the features in Lotus Connections, data in the Blogs feature is exposed as Atom feeds. The blog feed can be accessed at the following location on your blog server, where {handle} is the ID created for the blog in question. You can find the full list of available Blogs collections and feeds in the Blogs Service document (/service/atom).

This returns an Atom feed containing recent posts. You can retrieve older posts with paging.

You can constrain (filter) the set of returned posts by using the parameters listed in table 5. In the absence of any constraints, all posts are returned. You cannot filter both search and tags in the same query.

Table 5. Blogs URL parameters
ParameterMeaningNotes
search Full-text search Perform a full-text search against the blog identified by {handle}.
tagsRestricts the returned entries to those containing the tag N/A
pagePage number to return. Paging starts at 0.
ps Number of entries per page. N/A

The result of the call is shown in listing 14.

Listing 14. Truncated Atom feed from the Blog feature
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://purl.org/atom/app#">
    <title type="html">Megan Moyer's Weblog</title>
    <subtitle type="html">Social Networking Potential </subtitle>
    <id>https://paxos.lotus.com/blogs/snbizpotential/feed/entries/atom</id>
    <link rel="self" type="application/atom+xml" href="https:// 
    connections.company.com/blogs/snbizpotential/feed/entries/atom" />
    <link rel="alternate" type="text/html" href="https:// 
    connections.company.com/blogs/snbizpotential/" />
    <link rel="replies" type="application/atom+xml" href="https:// 
    connections.company.com/blogs/snbizpotential/feed/comments/atom" />
    <link rel="first" type="application/atom+xml" href="https:// 
    connections.company.com/blogs/snbizpotential/feed/entries/atom" />
    <app:categories href="https:// 
    connections.company.com/blogs/snbizpotential/feed/tags/atom"/>
    <updated>2007-07-18T12:36:29-04:00</updated>
   <generator uri="http://www.ibm.com/xmlns/prod/sn" 
   version="1.0">Lotus Connections - Blogs</generator>
    <entry xml:lang="en-US" >
        <id>https:// connections.company.com/blogs/snbizpotential/entry/
        new_article_on_lotus_quickr</id>
        <title type="html">New article on Lotus Quickr connectors</title>
        <author><name>Megan Moyer</name><email>
        user@mail.com</email></author>
        <link rel="alternate" type="text/html" href=
        "https://paxos.lotus.com/blogs/snbizpotential/entry/new_article_on_lotus_quickr"/>
        <published>2007-07-18T12:23:48-04:00</published>
        <updated>2007-07-18T12:23:48-04:00</updated> 
        <category term="connectors" />
        <category term="lotus-quickr" />
        <category term="quickr-connectors" />
        <content type="html">{Post content here}</content>
    </entry>
</feed>

Next, create a new blog entry to donquixote blog. Here you use the API to post a new entry as shown in
listing 15.

Listing 15. HTTP command, parameters, and body for posting a blog entry
POST /donquixoteBlogEntriesCollectionURL HTTP/1.1
Host: www.connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 246
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<author><name>Frank Adams</name></author>
<title type="text">Don Quixote</title>
<content type="text">Don Quixote begins his adventure to save 
Dulcinea del Toboso from the evil windmills.</content>
</entry>

A successful response from the server includes a link to the new entry as shown in listing 16.

Listing 16. Successful blog entry HTTP response
HTTP /1.1 201 Created
Date: Fri Jun 15 15:18:02 EDT 2007
Content-Type: application/atom+xml; type=entry
Location: newly created blog entry location

You can upload an image to the blog server to use in a future post as shown in listing 17. Topic "Publishing to a Blog" in the API documentation explains how to obtain the Blogs Media Link Entries collection URL used for uploading new image files.

Listing 17. HTTP command, parameters, and body for uploading an image
POST /donquixoteBlogMediaCollectionURL HTTP/1.1
Host: www.connections.renovations.com
Content-Type: image/jpeg
Content-Length: 4687
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
[A binary representation of the image file, sample.jpg, would be shown here.]

A successful response from the server includes an Atom entry with data about the file uploaded as shown in
listing 18.

Listing 18. Successful HTTP response for an image upload
HTTP /1.1 201 Created
Date: Fri Jun 15 15:11:02 EDT 2007
Content-Type: application/atom+xml; type=entry
Location: newlyCreatedMediaEntryURL

Here you update the content of an existing blog entry as shown in listing 19.

Listing 19. HTTP command, parameters, and body for updating an entry
PUT /blogEntryEditURL HTTP/1.1
Host: www.connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 390
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<id>blogEntryURL</id>
<title type="text">Don Quixote</title>
<content type="html"><b><font color="red">Don Quixote</font></b> 
begins his adventure to save Dulcinea del Toboso from the evil windmills.</content>
<category term="donquixote" />
<category term="adventure" />
</entry>

A successful response from the server is indicated by an HTTP 200 code:

HTTP /1.1 200 OK

You can delete an existing blog entry as shown in listing 20.

Listing 20. HTTP command and parameters for deleting a blog entry
DELETE /blogEntryEditURL HTTP/1.1
Host: www.connections.renovations.com
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl

A successful response from the server is indicated by an HTTP 200 code:

HTTP /1.1 200 OK


Reading from Communities

Communities APIs support read and write access to Communities content. The read APIs return an Atom feed. The write APIs publish, edit, or delete Communities content using the Atom Publishing Protocol (APP). You can find the full list of Communities collections and feeds in the Atom Service document (/services/atom).

To read from Communities, you need to issue an HTTP GET call to the service URL endpoint. The service URL endpoint syntax is:

<scheme>://<host name>/<context path>/service/atom/<service path>

Tables 6-8 show various collection and feed URLs and optional query parameters you can use to filter the feed content.

Table 6. Service path
Service pathReturned feedMeaningParameter
The URL is found in Service Document. <collection title="All Communities"> All CommunitiesReturns a list of all public communities in Communities.All Communities
Query Parameters (table 7)
<collection title="My Communities">/CompletedReturns a list of Communities that the authenticated user is a member of.My Communities
Query Parameters (table 7)
Found in the href attribute of <link rel="http://www.ibm.com/xmlns/prod/sn/bookmarks"> element of each Community Community bookmarks Returns a list of bookmarks for a Community.
Found in the href attribute of <link rel="http://www.ibm.com/xmlns/prod/sn/feeds"> element of each Community Community feeds Returns a list of feeds for a Community.
Found in a Communities FeedCommunity membersReturns the members of the specified Community.
Table 7. All Communities and My Communities query parameters
ParameterMeaningValue
tagThe tag name to query N/A
emailThe user's email address N/A
searchThe full-text search termN/A
sortFieldThe sort field to be usedname, count, lastmod
ascWhether the order should be ascending or descendingtrue, false
outputTypeTag cloudcategories
Table 8. Paging parameters
ParameterValueMeaning
pageThe current page numberPage number
ps The page size Page size

NOTE: Paging parameters can be applied to all query APIs.

This URL example returns a feed form of the Communities that the authenticated user is a member of:

http://connections.renovations.com/communities/service/atom/communities/my?page=1&ps=2

The result of this call is displayed in listing 21.

Listing 21. Return for My Communities
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://purl.org/atom/app#" 
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:snx="
http://www.ibm.com/xmlns/prod/sn">
<id>http://connections.renovations.com/communities/service/atom/communities/
my?page=1&ps=2</id><updated>2007-07-20T20:07:42.784Z</
updated><title type="text">Communities</title><link href=
"http://connections.renovations.com/communities/service/html/mycommunities" 
rel="alternate"></link><generator uri=
"http://connections.renovations.com/communities">
Lotus Connections - Communities</generator>
<link href="http://connections.renovations.com/communities/service/atom/
communities/my?ps=2" rel="self"></link>
<link href="http://connections.renovations.com/communities/service/atom/
introspection" rel="service" type="application/atomserv+xml; 
charset=UTF-8"></link><link href="http://connections.renovations.com/
communities/service/atom/communities/
my?ps=2&outputType=categories" rel="http://www.ibm.com/xmlns/prod/sn/tag-cloud" 
type="application/atomcat+xml; charset=UTF-8"></link>
<entry>
<id>http://connections.renovations.com/communities/service/atom/community/
instance?communityUuid=75DG0921865483F11D4A308416E78200001C</id>
<title type="text">HSBC</title>
<summary type="text"></summary>
<content type="html"></content>
<published>2007-06-21T21:39:17.293Z</published>
<author><name>Frank Adams</name><email>
frankadams@renovations.com</email></author>
<updated>2007-06-21T21:39:17.342Z</updated>
<contributor><name>Frank Adams</name><email>
frankadams@renovations.com</email></contributor>
<category term="community" scheme="http://www.ibm.com/xmlns/prod/sn/
type"></category>
<link href="http://connections.renovations.com/communities/service/atom/community/
instance?communityUuid=75DG0921865483F11D4A308416E78200001C" rel="self"></
link><link href="http://connections.renovations.com/communities/service/atom/community/
instance?communityUuid=75DG0921865483F11D4A308416E78200001C" rel="edit"></
link><link href="http://connections.renovations.com/communities/service/html/
communityview?communityUuid=
75DG0921865483F11D4A308416E78200001C" rel="alternate" type="text/html"></
link><link href="http://connections.renovations.com/communities/service/html/
image?communityUuid=
75DG0921865483F11D4A308416E78200001C&lastMod=1182461957342" 
rel="http://www.ibm.com/xmlns/prod/sn/logo"></link>
</entry>
….. More entries ….
</feed>

Writing to Communities

You can create, modify, and delete Communities using HTTP POST, PUT, and DELETE calls.

Create a new community to My Communities collection

My Communities is the collection of Communities for the authenticated user. Each community is listed in the My Communities feed as an entry document. To create a new community, make an HTTP POST call to the My Communities collection URL (see table 6) with the proper Atom entry. The example in listing 22 creates a Community with a title and content wrapped as an Atom entry.

Listing 22. Creating a community
POST /MyCommunitiesCollectionURL HTTP/1.1
Host: www.connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 371
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:snx="http://www.ibm.com/xmlns/prod/sn">
<title type="text">Beautiful Dulcinea</title>
<content type="html">All about <b><i><font color="blue">beautiful 
Dulcinea<font></b></content>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="community" />
<snx:communityType>public</snx:communityType>
</entry>

Add a new bookmark to an existing community

To create a new bookmark in an existing Community, make an HTTP POST call to the bookmark collection URL with the proper Atom entry. Topic “Publishing to a Community” in the API documentation explains how to obtain the bookmark collection URL used to create a new community bookmark. The example in listing 23 creates a bookmark in a community with a title and description and bookmark link wrapped as an Atom entry.

Listing 23. Creating a bookmark in a community
POST communitiesBookmarkCollectionURL HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 395
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title type="text">Don Quixote Homepage</title>
<content type="text">Don Quixote begins his adventure to save Dulcinea 
del Toboso from the evil windmills.</content>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" 
term="bookmark">Bookmark</category>
<link href="http://www.donquixote.com/" />
</entry>

Update an existing bookmark entry

To update an existing bookmark, make an HTTP PUT call as shown in listing 24.

Listing 24. Updating a community
PUT /communitiesBookmarkEntryEditURL HTTP/1.1
Host: www.connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 403
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<entry xmlns="http://www.w3.org/2005/Atom">
<title type="text">Don Quixote Homepage</title>
<content type="html"><b>Don Quixote<b> begins his adventure to 
save <i>Dulcinea</i> del Toboso from the evil windmills.</content>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="bookmark" />
<link href="http://www.donquixote.com/" />
</entry>
HTTP /1.1 200 OK

Delete an existing bookmark entry

To delete an existing bookmark, make the call shown in listing 25.

Listing 25. Deleting a community bookmark
DELETE /communitiesBookmarkEditURL HTTP/1.1
Host: connections.renovations.com
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
HTTP /1.1 200 OK

Community member management

The Lotus Connections API allows you to work with community members, providing the option to add, update, delete, join, or leave a community.

Add a member to a community

To add a member to a community, we need to make an HTTP POST call to the member-list collection URL. This entry must contain a single Atom contributor element with an email subelement. Optionally, the poster can include an snx:role element, indicating whether a member is a member or owner. By default, member entries posts are assigned the member role. Upon a successful POST, the server returns an HTTP 201 (CREATED) response and the Location response header containing the instance URL of the newly created entry.

Listing 26 shows a POST made against a community member-list collection, adding the member.

Listing 26. Adding a member to a community
POST /CommunityMembersCollectionURL HTTP/1.1
Host: connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 395
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:snx="http://www.ibm.com/xmlns/prod/sn">
<contributor>
<email>fadams@renovations.com</email>
</contributor>
<snx:role>member</snx:role>
</entry>

Assuming this operation succeeded, the user receives this response:

Location: Newly created member entry URL

Update a member's role

Updating a member's role requires an HTTP PUT call of exactly the same format as described in the previous
section. Rather than executing against the member-list collection, the operation acts against the member entry:

(${member-list}&email=foobar@us.ibm.com)

Upon a successful update, the service returns an HTTP (200) response with no additional headers or content.

Delete a member from a member list

You delete a member by executing an HTTP DELETE call against the member instance. The request body should be empty. Upon a successful delete, the server returns an HTTP (200) response code with no additional headers.

Join a community

Joining a community happens in the same manner as creating a member with one distinction: The member being added is the user issuing the HTTP POST request against the community member-list.

Leave a community

Leaving a community happens in the same manner as deleting a member with one distinction: The member being deleted is the user issuing the HTTP DELETE request against the member instance.


Dogear

Getting a Dogear feed is just as easy as making an HTTP call. You can constrain (filter, select) the set of returned bookmarks using the following parameters shown in table 9. In the absence of any constraints, all public bookmarks are returned (along with the authenticated user's private bookmarks, if HTTPS is used).

Table 9. Dogear URL parameters
ParameterMeaningNotes
urlAny well-formed encoded URL Returns bookmarks for the given URL. This constraint trumps the others. If you use the url constraint, all other constraints are ignored.
emailInternet email address Returns bookmarks created by the given user.
tagOnly return bookmarks with a given tag Only returns bookmarks containing the given tag or tags.
This is a tag intersection.
networkFilters the bookmarks returned as to whether they are on the Internet or intranet *Intranet : Returns only bookmarks for resources available on the corporate intranet, that is, not externally visible.
*Internet : Returns only bookmarks for Internet resources, visible outside the intranet firewall.
Default is *all.
accessWhether or not to return private bookmarks *Private - Returns only private bookmarks
*Public - Returns only public bookmarks.
Default is *all.
searchAny well-formed full-text search query Performs a text search on the title, description, and tags of all bookmarks.
Orders results by relevance. Respects other constraints.
searchOperatorDefault operator between search terms. AND and OR are valid values. Used in conjunction with searchText parameter. Enabled request to override the system default operator for search queries.

In the example Dogear: Bookmarks with Tags: connections, this URL gets all public bookmarks with the tag connections:

https://connections.company.com/dogear/atom?tag=connections&lang=en_US

The result of the call is shown in listing 27.

Listing 27. Truncated example of an Atom feed containing Dogear bookmarks
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:snx=
"http://www.ibm.com/xmlns/prod/sn"
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <generator uri="http://www.ibm.com/xmlns/prod/sn" version="1.0">
  Lotus Connections - Dogear</generator>
  <title>Dogear: Bookmarks with Tags: connections</title>
  <link rel="self" type="application/atom+xml" 
  href="https://paxos.lotus.com/dogear/atom?tag=connections&lang=en_US" />
  <link rel="http://www.ibm.com/xmlns/prod/sn/tag-cloud" type=
  "application/atomcat+xml" href="https://paxos.lotus.com/dogear/tags?
  tag=connections&lang=en_US" />
  <link rel="next" href="https://paxos.lotus.com/dogear/atom?page=2&
  tag=connections&
  lang=en_US" type="application/atom+xml" />
  <link rel="last" href="https://paxos.lotus.com/dogear/atom?page=4&
  tag=connections&
  lang=en_US" type="application/atom+xml" />
  <link rel="alternate" type="text/html" href="https://paxos.lotus.com/dogear/html?
  tag=connections&lang=en_US" />
  <opensearch:totalResults>37</opensearch:totalResults>
  <id>tag:dogear.ibm.com,2005:feed:/?tag=connections&lang=en_US</id>
  <updated>2007-07-17T02:18:51-04:00</updated>
  <entry>
    <id> tag:dogear.ibm.com,2005:link:FA0G09210694FF14E35E570695D479000001</
    id>
    <title>The Connections Blog</title>
    <category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="bookmark" />
    <link href="http://lotusconnectionsblog.com/" />
    <content type="html">
      <![CDATA[ <div><p> BLOG Lotus Connections <br /> 
      </p></div> ]]>
	 </content>
    <published>2007-07-17T02:18:51-04:00</published>
    <updated>2007-07-17T02:18:51-04:00</updated>
    <category term="connections" />
    <category term="lotus" />
    <author>
      <email>user@company.com</email>
      <name>Joe User</name>
      <uri>https://connections.company.com/dogear/html?email=
      user%40company.com&
      lang=en_US</uri>
    </author>
    <snx:clickcount>1</snx:clickcount>
    <link rel="http://www.ibm.com/xmlns/prod/sn/same" 
    type="application/atom+xml" href="https://paxos.lotus.com/dogear/atom?for=
    http%3a%2f%2flotusconnectionsblog.com%2f&
    lang=en_US" />
  </entry>
</feed>

Create a bookmark

You have seen how to get the service document, so let's assume that you've gotten it for the Dogear service
document and you've found that the APP endpoint is at http://www.connections.renovations.com/dogear/api/
app?email=fadams@renovations.com. To create a bookmark, make an HTTP call to it with the proper Atom
entry. The example in listing 28 creates a bookmark with a description, two tags, and a title as indicated by the
Atom entry.

Listing 28. HTTP command, parameters, and body creating a bookmark
POST /dogear/api/app?email=fadams@renovations.com HTTP/1.1
Host: www.connections.renovations.com
Content-Type: application/atom+xml
Content-Length: 505
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
	<author><name>Frank Adams</name></author>
	<title>All about Don Quixote</title>
	<content type="html"><![CDATA[<b>Don Quixote</b> begins his 
	adventure to save Dulcinea del Toboso from the evil windmills.]]></content>
	<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term="bookmark" />
	<category term="tag1" />
	<category term="tag2" />
	<link href="http://en.wikipedia.org/wiki/Don_Quixote" />
	<category term="wiki" />
</entry>

The response from the server gives a pointer to the bookmark you have just created. See listing 29.

Listing 29. Successful HTTP response for creating a bookmark
HTTP /1.1 201 Created
Date: Thu Jun 14 14:27:38 EDT 2007
Content-Type: text/xml
Content-Length: 0
Location: http://www.connections.renovations.com/dogear/api/
app?url=http%3A%2F%2Fen.wikipedia.org%2Fwiki%2FDon_Quixote

Profiles

In Lotus Connections V1.0, Profiles supports only read-only feeds, but it expands its capabilities to support Atom Publishing Protocols for editing contents in the next release. There are still many opportunities, though for mash-up applications and integration with other Web and desktop applications using returned feeds.

There are a couple of notable things regarding the Profiles feed. First, only the profile type of Atom Entry document is supported using the atom:category element. Second, representation of a person is supported using a one-to-one representation of vCard to hCard format as the value of the atom:content element.

Table 10 lists the current Profiles feed URLs and their optional parameters.

Table 10. Profile feed URL paths and parameters
Atom feed pathParameter
/profiles/atom/profile.do email
/profiles/atom/peopleManaged.do email
/profiles/atom/reportingChain.do email
/profiles/atom/search.dojobTitle, city, name, phoneNumber,
profileTags, jobTitle, search

To take advantage of feeds that are produced by your Profiles server, send a HTTP GET request to one of the supported feed URLs. Depending on the specified feed URL with the combination of one or more optional parameters, you see variations in retrieved contents. By appending the email parameter to the /atom/profile.do URL, the HTTP GET request returns Frank Adams's profile. See listing 30.

Listing 30. HTTP GET request
GET /profiles/atom/profile.do?email=fadams@renovations.com HTTP/1.1
Host: www.connections.renovations.com
Content-Type: application/atom+xml
Authorization: Basic RG9uIFF1aXhvdGU6Um9jaW5hbnRl

On a successful GET request, the server returns the feed document shown in listing 31.

Listing 31. Feed document
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:fh=
"http://purl.org/syndication/history/1.0">
<id>tag:profiles.ibm.com,2006:feed</id><fh:complete><
/fh:complete>
<generator uri="http://www.ibm.com/xmlns/prod/sn" 
version="1.0">Profiles</generator>
<title type="text">profile with email fadams@renovations.com</title>
<author>
<name>Profiles</name>
</author>
<updated>2007-07-14T09:50:15.788Z</updated>
<link rel="self" type="application/atom+xml" href=
"http://connections.renovations.com/profiles/atom/
profile.do?email%3Dfadams%40renovations.com"></link>
<entry>
<id>tag:profiles.ibm.com,2006:entry927579897</id>
<category scheme="http://www.ibm.com/xmlns/prod/sn/type" term=
"profile"></category>
<title type="text">Frank Adams</title>
<updated>2007-07-14T09:50:15.788Z</updated>
<link rel="self" type="application/atom+xml" href=
"http://connections.renovations.com/
profiles/atom/profile.do?uid%3D927579897%26format%3Dfull"></link>
<summary type="text">Profile information for Frank Adams</summary>
<content type="xhtml"><div xmlns="http://www.w3.org/1999/xhtml"><
span class="vcard"><div><img class="photo" 
src="http://connections.renovations.com/profiles/photo.do?uid=927579897&
lastMod=1186152801000"></img></div><div><a class="fn url"
href="http://connections.renovations.com/profiles/atom/profile.do?uid=927579897">
Frank Adams</a></div><div><a class="email" href=
"mailto:fadams@renovations.com">fadams@renovations.com</a></div><
div class="x-groupwareMail" style="display:none">Frank Adams/renovations/IBM</
div></content>
</entry>
</feed>

Conclusion

As we have demonstrated in this article, the Lotus Connections API implementation is an XML-based interface allowing independent computer programs to easily interact with Lotus Connections data and services. The abilities to extend Lotus Connections and to easily create mash-ups, plug-ins, or new interfaces are key features of the product. The API allows you to access and update much of the same information you can access and update through the Lotus Connections user interface. Using Atom to specify the interface, Lotus Connections does not get involved with implementation details, giving you the power to extend this social software to meet your needs and to integrate with your applications.


Acknowledgments

The authors of this article would like to thank the Lotus Connections Atom API Review team for their efforts and resources that made this article possible: Rob Yates (Chair), Andy Myers (Activities), Judy Piper (Activities), James Snell (Blogs), Alex Kordun (Communities), David Brooks (Dogear), and Colleen Connearney (Profiles). Also, thank you to Dan Gurney from the Plug-in team for his great work and willingness to provide help and support.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=253881
ArticleTitle=Deploying IBM Lotus Connections: Application programming interface
publish-date=09112007