RSS Channels on the Platform
RSS is a widely used technology that allows users to subscribe to website content they're interested in. The content provider organizes information in a defined information structure called an RSS channel. Users can then subscribe to the channel via a piece of software called an RSS feed. Once a user subscribes to an RSS feed, content updates are automatically delivered, without the user having to check the individual websites for updates.
Many of the operations in the Akana API Platform API use RSS in the response. In general, GET operations that return any type of list return the information as an RSS channel, in either JSON or XML format. For examples, see Akana API Platform Objects Returned as RSS Channels below.
The RSS channel always includes the required summary information, and can also hold a list of items. In some cases, the RSS structure includes additional extension elements. In cases where Akana API Platform operations use additional extension elements, they are described in the documentation for the applicable operation.
This topic includes the following information:
RSS Fields
The following tables describe elements that might appear in RSS feeds returned by the Akana API Platform API.
In general, platform RSS responses include a few main values, and then one or more items, each with a set of values. These two sets of information are described in the tables below. For examples, refer to Akana API Platform Objects Returned as RSS Channels below.
RSS response main values:
| Header | Description |
|---|---|
| title | Name of the RSS feed. In the Akana API Platform, examples are Application Contracts (for GET /api/apps/versions/{AppVersionID}/contracts), APIs (for GET /api/apis), User Notifications (for GET notifications/types). |
| item | One or more items specific to the individual RSS feed. For possible item structures, and likely values, refer to the table below. |
| version | The RSS version is always 1.0. |
RSS item values:
| Header | Description |
|---|---|
| link | The URL to the HTML page with details of the item. |
| description | Short description of the item. This may be the actual description of the item or an automatically generated descriptor of the resource based on its attributes. |
| comments | Relative URI to the comment list page for the item. |
| CommentsPreview | Extensibility element holding a preview of comments for an item. Optional. |
| Marks |
Extensibility element that describes whether the item has been marked("liked") by a user, and if so how often. It includes a numeric count and a boolean value, IsMarkedByReader, indicating whether the current user (if a user is logged in) marked the Board item. Example: "Marks" : {
"Count" : 0,
"IsMarkedByReader" : false
}
|
| category |
An array of optional elements of type Category. Each category has two parts: value and domain. The domains for which values are defined are:
|
| enclosure | A media file that needs to be rendered with the item. This field is standard to the RSS feed structure, but isn't used by the Akana API Platform API. |
| pubDate | The date the item was created, or last modified, formatted in Coordinated Universal Time (UTC). |
| guid | Globally unique identifier for the item (FDN). |
| Action |
An extensibility element for an action event that is valid for a specific item returned in the RSS channel. Used to call a JavaScript action. In some cases, actions that can be taken might be different for each of the items returned. For example, if the RSS channel is a list of tickets, some might be open and some might be closed. The action "Close" is only valid for open tickets. For a list of API access contracts, if a specific contract is suspended then "Suspend" is not a valid action for that contract. In the Action field, the RSS channel includes a list of valid dynamic actions available, per object, so that the application can determine what actions are valid for a specific object. This is only applicable to API access requests, tickets, group membership requests, and legal agreements. For information on valid workflow actions for different types of resources, see Workflow Actions Note: Actions that are always valid are not included. For example, someone can always comment on a ticket, so the action "Comment" is not included. |
| Icon | Extensibility element for an icon that is rendered along with the item. Used to show state or attribute of the item. |
| EntityReferences |
Extensibility element for referring to an entity in the system. Optional. When an HTTP GET operation in the platform returns information in the form of an RSS channel, it very often includes entity references. Where an RSS item represents an object, the entity references include additional information about the object. For example, if the RSS channel returns information about an app version, the entity reference might include information about the app to which the app version belongs. All relevant relationships to the object returned in the RSS response are represented in the entity references. Note: Each item in an RSS feed could include a list of EntityReferences. Each EntityReference in the list is another object that is somehow related to the object in the RSS feed item. In the past, we put EntityReference objects directly in the RSS item. This caused difficulties with JavaScript interpreting different EntityReference elements when there were one versus many. For this reason, we added EntityReferences as a separate element. In viewing the RSS feed results, you can ignore the EntityReference elements directly in the RSS item. Use only the EntityReference elements in the RSS item. Later, we will be removing the EntityReference objects references in the RSS item itself. |
| AuthoringUser | Information identifying the item's author. Optional. |
| Image | Extensibility element for an icon to be shown with the item, such as a company logo, user photo, or avatar. If this does not exist, the icon for the item can be determined by convention based on the item type. For example, ~/api/icon.png. Optional. |
Paging of Returned RSS Items
When the total number of items in a list exceeds the search results page size, the list is broken down into pages, where each returned RSS channel is one page. OpenSearch 1.1 elements are used as extensions to the RSS channel element to describe how the returned channel represents a page and where it fits in the overall list.
For example, if the search results are limited to elements 101-200 out of a total of 1000 possible results, that information is included in the RSS channel, in the OpenSearch fields: totalResults, startIndex, and itemsPerPage. Including this information allows the user to get the broader picture of the possible search results available. If the full set of possible search results is returned, we don't include totalResults.
Definitions for the paging properties are listed below.
| Paging Property | Description |
|---|---|
| startIndex | The starting position for the search results page. This corresponds to the start value in the request parameters. |
| totalResults | The total number of results matching the request, even if a subset of total results is returned. |
| itemsPerPage | The number of search results to be displayed on the search results page. This corresponds to the count value in the request parameters. |
A JSON example of OpenSearch elements used in an RSS channel is shown below. Ellipses indicate content omitted from the JSON object.
{
"channel" : {
...
"startIndex" : 10,
"totalResults" : 1000,
"itemsPerPage" : 10,
"item" : [
RssItem>,
...
]
},
"version" : "1.0"
}
Akana API Platform Objects Returned as RSS Channels
The following is a list of some of the types of Akana API Platform information that are returned as RSS channels:
The properties in the objects above are mapped to specific fields in the RSS channel. For details, refer to the documentation pages for specific operations.