Deploying IBM Lotus Connections: Application programming interface

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 J. Piper is a SDK developer for the IBM Lotus Connections Activities team. She has been responsible for bringing Activities Atom APIs into compliance with the latest Atom Publishing Protocol specifications. She was actively involved in the Lotus Connections team collaboration work to ensure consistency in the Atom feeds throughout the Connections Services. She earned her B.S. in Computer Science from University of Utah and joined IBM in 2004.

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

View more content in this series

Tag this!

Date: 11 Sep 2007
Level: Intermediate
Activity: 2576 views

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 path	Returned feed	Meaning	Parameter
/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
/completed	Completed	Returns a feed that contains the authenticated user's Activities that are marked completed.	- Activities Common Query Parameters
/everything	Everything	Returns 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 Document	Trash	Returns 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 Document	An activity	An 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 feed	ACL member list	The 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
/ tags	Overview tag cloud	Returns overview tag cloud when no parameters are specified.

Table 2. Activities common query parameters

Parameter	Value	Meaning
page	The current page number	The current page number.
ps	The page size	The page size.
tag	Limit the Activities to only those with this tag	Only a single tag is supported.
sortfields	List of sortfields to sortby	NAME, CREATED, LASTMOD.
sortorder	The sort order	0 (ascending), 1 (descending) - multiples separated by commas to match sortfields.
search	Query string	Searches across title and description â€“ OR.
casesensitive	Yes, no	Specifies if a search should be case-sensitive or not. tThe default is not case-sensitive.
nodetype	Type of an entry being requested	Activity, comment, bookmark, todo, file, email, chat

Table 3. Activities query parameters

Parameter	Value	Meaning
deleted	yes, no, only	Whether or not to include deleted Activities/content
public	yes, no, only	Whether or not to include public Activities/content
templates	yes, no, only	Whether or not to include templates

Table 4. To Do's query parameters

Parameter	Value	Meaning
Assignedto	assignee email address	Returns only items assigned to a specified person.
completed	yes, 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

Parameter	Meaning	Notes
search	Full-text search	Perform a full-text search against the blog identified by {handle}.
tags	Restricts the returned entries to those containing the tag	N/A
page	Page 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 path	Returned feed	Meaning	Parameter
The URL is found in Service Document. <collection title="All Communities">	All Communities	Returns a list of all public communities in Communities.	All Communities Query Parameters (table 7)
<collection title="My Communities">/	Completed	Returns 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 Feed	Community members	Returns the members of the specified Community.

Table 7. All Communities and My Communities query parameters

Parameter	Meaning	Value
tag	The tag name to query	N/A
email	The user's email address	N/A
search	The full-text search term	N/A
sortField	The sort field to be used	name, count, lastmod
asc	Whether the order should be ascending or descending	true, false
outputType	Tag cloud	categories

Table 8. Paging parameters

Parameter	Value	Meaning
page	The current page number	Page 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

Parameter	Meaning	Notes
url	Any 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.
email	Internet email address	Returns bookmarks created by the given user.
tag	Only return bookmarks with a given tag	Only returns bookmarks containing the given tag or tags. This is a tag intersection.
network	Filters 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.
access	Whether or not to return private bookmarks	Private - Returns only private bookmarks Public - Returns only public bookmarks. Default is *all.
search	Any 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.
searchOperator	Default 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 path	Parameter
/profiles/atom/profile.do	email
/profiles/atom/peopleManaged.do	email
/profiles/atom/reportingChain.do	email
/profiles/atom/search.do	jobTitle, 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

Read the developerWorks article, "Deploying IBM Lotus Connections: Planning and architecture considerations."
Read the developerWorks article, "Deploying IBM Lotus Connections: Post-installation tuning."
Read the developerWorks article, "Deploying IBM Lotus Connections: Maintenance."
Read the developerWorks article, "Deploying IBM Lotus Connections: Troubleshooting."
Read the developerWorks article, "Deploying IBM Lotus Connections: Branding and customization."
Read the developerWorks article, "Deploying IBM Lotus Connections: Integrating with other systems."
Read the developerWorks article, "IBM Lotus Connections: Enhancing productivity with social computing."
Read the developerWorks article, "An overview of the Atom 1.0 Syndication Format."
Visit the developerWorks Lotus Connections page.
Read the Lotus Connections V1.0 Reviewer's Guide.
Consult the Lotus Connections documentation page for details on the installation, configuration, and administration of Lotus Connections.

Discuss

Participate in the discussion forum.
Participate in the developerWorks Lotus team blog.

About the authors

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

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

author1-email=mac_guidera@us.ibm.com

author1-email-cc=

author2-email=fjania@us.ibm.com

author2-email-cc=