Atom Feed Guide — Pearl Comments™ Server

Atom Feed Guide — Pearl Comments™ Server
Copyright © 2004-2007 Pearl Crescent, LLC

Table of Contents

1. Introduction
2. The Components of a Pearl Comments Feed URL
3. Atom Feed URL Examples

Atom is an XML-based publication format that describes lists of related information called "feeds." Atom is supported by feed reader software (sometimes called aggregators) such as NetNewsWire and FeedDemon. Atom is also supported by the Firefox browser's Live Bookmarks feature and by many other applications. Atom is a proposed Internet standard that will probably supplant RSS over time. You can learn more about Atom at the AtomEnabled web site (http://atomenabled.org/).

The Pearl Comments Server provides authenticated Atom 1.0 feeds. The components of a feed URL determine which comments are included in the feed. For example, a feed URL like the following one may be used to retrieve all comments for the topic "interesting":

http://hostname/pearlcomments/atom?url=*&filter=subject%3Dinteresting

(replace hostname with the name of the computer on which the Pearl Comments Server is installed). Or, if you are using the Pearl Comments hosted service, you would use a feed URL like this one:

https://use.pearlcomments.com/orgid/pearlcomments/atom?url=*&filter=subject%3Dinteresting

(replace orgid with the Organization ID that was chosen when your Pearl Comments subscription was created).

Because all feeds provided by the Pearl Comments Server are authenticated feeds, you must provide a valid Pearl Comments user name (ID) and password when accessing each feed. Some feed readers will automatically prompt you to authenticate while others require that you check a box or take some other action to indicate that the feed requires authentication.

2. The Components of a Pearl Comments Feed URL

The components that make up a Pearl Comments Atom feed URL are:

The base URL component which is the same for all feed URLs, e.g.,
http://hostname/pearlcomments/atom?
Or, if you are using the Pearl Comments service:
https://use.pearlcomments.com/orgid/pearlcomments/atom?
An url query parameter (required). To match comments for all web pages (like the Any Page tab in the Pearl Comments browser extension does), use url=*. To limit the comments returned to those for a specific page (like the Current Page tab in the Pearl Comments browser extension does), provide the URL of the page, e.g., url=https://www.google.com/. Special characters such as spaces within the page URL should be replaced with a hexadecimal escape sequence (e.g., %20).
A filter query parameter (optional). The filter parameter is made up of a comma-separated list of filter components, each of which consists of a property name (e.g., creator), an operator (e.g., =), and a value (e.g., Jan Jones). Each filter component must match a property of a comment in order for that comment to be included in the Atom feed. Special characters, including those used for operators, should be converted to hexadecimal escape sequences (e.g., replace = with %3D). Table 2-1 lists the different kinds of filter components that you may use.

Property Name	Available Operators	Description
creator	=	The full name or user name (ID) of the person who added the comment. For example, the filter component `creator%3DSusan%20Jones` matches all comments created by Susan Jones (`%3D` and `%20` are the hexadecimal escape sequences for the `=` and space characters).
created	= != < >	The date and time when the comment was added. The format used is `yyyy-mm-ddThh:mm:ssZ`, e.g., `created%3E2005-11-01T08:30:00Z` matches all comments created after 8:30am GMT on November 1st, 2005 (`%3E` is the hexadecimal escape for the `>` character).
date	= != < >	The date and time a comment was last modified. The format used is the same as for the created property.
status	= !=	The Status associated with a comment. The possible values are: `Assigned` (shown as "In Progress" in the Pearl Comments browser extension) `Resolved` (shown as "Completed" in the Pearl Comments browser extension) `Closed` For example, to match all comments that are marked as "In Progress", use a filter component like: `status%3DAssigned`.
subject	= != < >	The topic associated with the comment, e.g., `text content`. Remember to replace spaces and other special characters in the topic with hexadecimal escape sequences, e.g., `subject%3Dtext%20content`.

Table 2-1 — Filter Components

3. Atom Feed URL Examples

The following examples assume that the Pearl Comments service is being used with an organization ID (orgid) of myorg.

Example 3-1. Comments associated with the www.example.com web page:

https://use.pearlcomments.com/myorg/pearlcomments/atom?url=http://www.example.com/

Example 3-2. Comments created by Mary Smith:

https://use.pearlcomments.com/myorg/pearlcomments/atom?filter=creator%3DMary%20Smith&url=*

Example 3-3. Comments created by the person with the user name (ID) bob that have a topic of "to do":

https://use.pearlcomments.com/myorg/pearlcomments/atom?filter=creator%3Dbob,subject%3Dto%20do&url=*

Example 3-4. Comments that have a topic of "content" and are not Closed:

https://use.pearlcomments.com/myorg/pearlcomments/atom?filter=subject%3Dcontent,status!%3DClosed&url=*

Example 3-5. Comments that have been modified on or after July 1st, 2007:

https://use.pearlcomments.com/myorg/pearlcomments/atom?filter=date%3E2007-07-01T00:00:00Z&url=*