RSS Advisory Board

RssCloud API

Archivist's Note: This documentation applies to RSS 2.0.

1. Introduction

This is version 1.1 of this document.

The RssCloud Application Programming Interface (API) is an XML-RPC and SOAP 1.1 web service that enables client software to be notified of updates to RSS documents. A server (called the "cloud") takes notification requests for particular RSS documents.

When a monitored document changes, the cloud calls a remote method on all interested clients to note the update.

2. Conventions

In this specification, the key words must, must not, required, shall, shall not, should, should not, recommended, may and optional are to be interpreted as described in RFC 2119.

3. Methods

The interface consists of two requests: a client-to-cloud call to request notification and a cloud-to-client call to perform notification.

3.1. Client Request

A notification request from a client to the cloud must contain five parameters:

  1. The name of the remote procedure the cloud should call on the client upon an update
  2. The client's TCP port
  3. The client's remote procedure call path
  4. The string "xml-rpc" if the client employs XML-RPC or "soap" for SOAP
  5. A list of URLs of RSS documents that the client seeks to monitor

The cloud must return the boolean true if the cloud successfully registers the request or false otherwise.

The request for notification must be sent from the IP address that will receive notifications. A client that connects to the Internet through a firewall or some form of network address translation (NAT) might not be able to receive calls back from the cloud.

3.2. Cloud Request

An update notification from the cloud to a client must contain one parameter, the URL of the RSS document that changed.

The client must return the boolean true.

4. Frequency

Two conventions govern the client-cloud relationship: The cloud should discard a notification after 25 hours and clients should request to monitor a particular URL once every 24 hours.

A. Contributors

The interface was created by Dave Winer in January 2001 and originally implemented in Radio UserLand.

License

This specification is offered under the terms of the Attribution/Share Alike Creative Commons license. The author of this document is the RSS Advisory Board, based on original work by Dave Winer.