Getting started 

---

If you are using the Atom API for the first time, follow these tips for getting started.

Before attempting to write a program that makes calls to the Lotus® Connections Atom APIs, test the syntax you are using to specify the resources and parameters in your requests. You can do this using one of the following tools:

web browser

Enables you to send GET requests and perform searches.

HTTP request generation tool

Enables you to create and edit content in addition to performing searches and sending GET requests.

Use one or both of these tools to save time by testing your syntax before you tackle the added complications of programming an application.

web browser

Retrieve information from the Lotus Connections applications in Atom format. To do so, complete the following steps:

1. Open a standard web browser.
2. Access the Lotus Connections application from which you want to retrieve information.
3. Authenticate with the application by providing a user name and password. If you are not asked to authenticate with the application immediately, perform an operation that forces you to authenticate. For example, do the following actions:
• Blogs: Click the My Blog tab.
• Bookmarks: Click the My Bookmarks tab.
• Communities: Click the My Communities tab.
• Profiles: Click the My Profile tab.
  
  
4. Type a request into the browser's address or location field, and then submit it.
   
For example, you can type one of the following requests:
• Activities: To search for all complete activities that you belong to, type the following URL:

https://activities.enterprise.example.com/activities/service/atom2/completed



• Blogs: To return all of the comments added to a blog, open the blog, and then add feed/comments/atom to the end of the blog's URL. For example:

http://blogs.enterprise.example.com/blogs/writer/feed/comments/atom



• Bookmarks: To retrieve a list of popular bookmarks, type the following URL:

https://dogear.enterprise.example.com:9443/dogear/atom/popular



• Communities: To return a list of all your communities, type the following URL:

http://communities.enterprise.example.com:9080/communities/service/atom/

 communities/my



• Home page: To search all of the applications for content that you have access to which contains the word blue, type the following URL:

https://home.enterprise.example.com:9443/homepage/atom/mysearch/results?

 query="blue"



• Profiles: To search for a person's report-to chain, type the following URL:

https://profiles.enterprise.example.com:9443/profiles/atom/reportingChain.do?

 userid=7fb4abl0-8f0a-1028-8b5a-db08933b51b2



The server returns the results

5. If the server returns a readable web page and you want to see the XML source, right-click the page and select the option to view the page source.
   

HTTP request generation tool

An example of a HTTP request generation tool is cURL. Using cURL and tools like it, you can quickly send requests and see what is returned.

There is no requirement that you install cURL. You can use whichever HTTP generation tool that you prefer. This tool is one example of the many tools available that can help new users get started with Atom. For more information about cURL, go to the following external web site:

http://curl.haxx.se/

The following requests are examples of how to use cURL to make Atom calls:

• To search all of your to-do items, and then order the returned Atom content to display the most recently modified to-do items first and write them to a file named getOrderedTodos.xml, you could use the following cURL command:

curl "https://activities.enterprise.example.com:9444/activities/service/atom2/

 todos?sortfields=LASTMOD&sortorder=0" -u Amy_Jones@us.example.com -k -L -v 

 -o getOrderedTodos.xml



• To create a blog post, you could define the blog post entry in a file called myPost.xml, and then use the following cURL command to post it to the edit href of the weblog entries feed for your blog:

curl POST --post301 --post302  --data "@myPost.xml" --header "Content-Type: application/atom+xml" 

"https://blogs.enterprise.example.com:9443/blogs/idwriter/api/entries" -u Amy_Jones@us.example.com -k -L -v



• To approve a blog entry awaiting approval before it can be posted, define the action you want to take in a file called acceptEntry.xml, and then use the following cURL command to post it to the moderation action feed:

curl -X POST --post301 --post302 --header "Content-Type: application/atom+xml" --data "@approveEntry.xml" -k -L -v 

"http://enterprise.example.com/blogs/home/api/actions/approval/entries" -u moderator@example.com 



• To retrieve the Bookmarks service document and write it to a file called bookmarksServiceDoc.xml, you could use the following cURL command:

curl "http://dogear.enterprise.example.com:9084/dogear/api/app" -L 

 -u Suzy_Jones@us.example.com -k -v -o bookmarksServiceDoc.xml



• To retrieve a forum topic from a community, you would retrieve the forum topics feed, and then use the following cURL command to retrieve one topic from the feed and write it to a file called getForumTopic.xml:

curl "https://communities.enterprise.example.com:9443/communities/service/atom/

 community/forum/topics?communityUuid=353G09211F19EE8AB425BD37C0B9DD00000A&

 topicUuid=3FEG09211E190EE3AA197D8D1BABJA000001" -u Amy_Jones@us.example.com -k 

 -L -v -o getForumTopic.xml



• To delete a community, retrieve the resource URL for the community that you want to delete by getting the service document. From the service document, determine the URL for the My Communities collection. Retrieve the My Communities feed and find the community you want to remove. Look for the URL in the href attribute of the <link rel="edit"> element and send a DELETE request to that URL. For example:

curl -X DELETE "https://enterprise.example.com/communities/service/atom/community/instance?

 communityUuid=f6ea747a-c82e-493a-a8dd-61ed573a09bb" -u asmith@example.com -k -v -L



• To retrieve a feed of your files, you could use the following cURL command:

curl "http://files.enterprise.example.com/files/basic/api/myuserlibrary/feed" -u ajones@example.com 

 -k -v -L -o MyFileLibrary.xml



• To retrieve a feed of all forums, you could use the following cURL command:

curl "http://forums.enterprise.example.com/forums/atom/forums" -v -L -o AllForums.xml



• To retrieve a feed of the top news stories, you could use the following cURL command:

curl "http://news.enterprise.example.ibm.com/news/atom/stories/top" -u ajones@example.com -k -v 

 -L -o newsTopStories.xml



• To search Lotus Connections for all content that contains the term "Red Sox" and write the content to a file named searchForRedSox.xml, you could use the following cURL command:

curl "https://homepage.enterprise.example.com:9443/homepage/atom/search/results?query=%22Red%20Sox%22" 

-u Suzy_Jones@us.example.com -k -L -v -o 

searchForRedSox.xml



• To search all profiles for users with the name Smith and write the returned Atom content to a file named getSmithProfiles.xml, you could use the following cURL command:

curl "http://profiles.enterprise.example.com:9080/profiles/atom/search.do?name=Smith" 

-u Amy_Jones@us.example.com -k -L -v -o getSmithProfiles.xml



• To retrieve a feed of your wikis, you could use the following cURL command:

curl "http://wikis.enterprise.example.com/wikis/basic/api/mywikis/feed" -u ajones@example.com 

 -k -v -L -o MyWikis.xml



Authenticating requests
Many operations, such as entry updates, require authentication by default. In addition, if the Lotus Connections administrator configures the servers to force authentication, all operations will first require you to authenticate.

Samples
Try out these sample applications to see the APIs in action.

Parent topic: Lotus Connections APIs