Onion Networks Gateway Advertisement API


XML-RPC allows developers to remotely invoke methods using HTTP POSTs.Responses are provided in the returned HTTP response. The Onion Networks Gateway uses an XML-RPC interface to provide control for its URL advertisement and leasing API. The expected requests and corresponding responses are defined in this document.


Invented in 1998 by Dave Winer, XML-RPC is a specification for making RemoteProcedure Calls through HTTP using XML as the syntax. Its popularity is due inlarge part to its great simplicity. It and its descendant, SOAP, are fast becoming _the_ standards for doing most anything programmatically over the web. For more information on the XML-RPC specification, its history, and relevant implementations refer to the RESOURCES section at the bottom of the document.


The Onion Networks Gateway is an application that runs in Java Application Servers. It works in conjunction with remote peers to provide a directory mapping URN identifiers to multiple URLs indicating where the corresponding document can be found.

Clients/Peers hosting the document contact the Gateway and make a statement that is the logical equivalent of “I’m X, and I have URN Y and URL Z, and I expect that to be the case for T duration.” The Gateway then responds with a statement essentially saying, “I believe that statement will only be true for T2 duration,” where T2 is less than or equal to the original T. It is then the responsibility of the Client to renew the lease with the Gatewaybefore duration T2 has expired.


The lease request/response pair occupy a single XML-RPC method call. The web object on which the method is called is named ‘advert’. In a standard Gateway installation the path to the leasing servlet is:



The ‘advert’ object exports a single method named ‘announceResource’. It take three parameters defined as follows:

        Name         | Type   | Description
        duration     | int    | The length of the requested lease in seconds.
                     |        | Identified as T in the above examples.
        urn          | string | The URN for the content the client holds
                     |        | Identified as Y in the above examples.
        url          | string | The URL where the content identified by 'urn'
                     |        | can be found.  Identified as Z above.


The ‘announce resource’ method above has an int return value which indicates the Gateway’s approval or rejection of the lease. This return value will be zero in the event that the Gateway elects not the store a lease.

Otherwise, the positive value indicates the number of seconds, T2 above, that the Gateway will retain the URN -> URL mapping requested. This value is always less than or equal to the requested duration. The client is expected to renew the lease before T2 seconds have elapsed by calling ‘announce resource’ again.


All errors are reported using the standard XML-RPC error reporting facility. The numerical error values contain no useful information. The text error messages are not suitable for displaying to users.


November 21, 2002:
– initial version


XML-RPC Specification: http://www.xmlrpc.com/spec


Published by