PSSAPI 0.9 (early draft)

Web, July 9 2003, by DeveloperDude.

This document describes the Portable and Simple Syndication API that allows pragramatic access to RSS databases. The PSS standard was developed in order to extend RSS 2.0 constructs beyong the RSS file. By incorporating the RSS elements into other APIs, we can then create new XML applications that interoperate well with RSS-based applications.

The PSSAPI includes three methods that can be expressed functionally as the following.

• pssapi.newItem(username, password, title, link, description)
• pssapi.editItem(username, password, title, link, description, guid)
• pssapi.deleteItem(username, password, guid)

By default the PSSAPI is implemented over the SOAP/HTTP RPC, but any RPC mechanism would suffice. It is strongly recommended that you use the SOAP/HTTP RPC where applicable. It is also strongly recommended that you use UsernameToken authorization as described in the standard WS-Security [http://www-106.ibm.com/developerworks/library/ws-secure/].

newItem

Adding a new item to an RSS feed, has the meaning of prepending the item to the beginning of the RSS data source.

Request

A sample pssapi.newItem request follows.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"  
	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" >
  <soap:Header>
    <wsse:Security>
      <wsse:UsernameToken>
        <wsse:Username>randy</wsse:Username>
        <wsse:Password>hello</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    <pssapi:newItem xmlns:pssapi="http://tempuri.org/object" >
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:title>My Title</pss:title>
        <pss:link>http://tempuri.org/object</pss:link>
        <pss:description>some content</pss:description>
      </pss:item>
    </pssapi:newItem>
  </soap:Body>
</soap:Envelope>

Response

A sample pssapi.newItem response follows. Note, the response is an echo of the request without the authentication module in the header. The response may add or change elements to fit the data sources specific RSS flavor. For instance, if the source was implementing RSS 0.91 or RSS 1.0, the items could change in style drastically.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" >
  <soap:Body>
    <pssapi:newItem xmlns:pssapi="http://tempuri.org/object" >
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:title>My Title</pss:title>
        <pss:link>http://tempuri.org/object</pss:link>
        <pss:description>some content</pss:description>
      </pss:item>
    </pssapi:newItem>
  </soap:Body>
</soap:Envelope>

Fault Response

A typical fault response follows.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" >
 <soap:Body>
  <soap:Fault>
   <soap:Code>
     <soap:Value>soap:Sender</soap:Value>
   </soap:Code>
   <soap:Reason>Request was incorrect.</soap:Reason>
  </soap:Fault>
</soap:Body>
</soap:Envelope>

editItem

Editing an existing item in an RSS feed, has the meaning of modifying the item in place in the RSS data source.

Request

A sample pssapi.editItem request follows.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
  xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" >
  <soap:Header>
 </soap:Header>
  <soap:Body>
    <pssapi:editItem xmlns:pssapi="http://tempuri.org/object" >
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:title>My Title</pss:title>
        <pss:link>http://tempuri.org/object</pss:link>
        <pss:description>some content</pss:description>
        <pss:guid>http://tempuri.org/guid</pss:guid>
      </pss:item>
    </pssapi:editItem>
  </soap:Body>
</soap:Envelope>

Response

A sample pssapi.editItem response follows. Note, the response is an echo of the request without the authentication module in the header. The response may add or change elements to fit the data sources specific RSS flavor. For instance, if the source was implementing RSS 0.91 or RSS 1.0, the items could change in style drastically.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" >
  <soap:Body>
    <pssapi:editItem xmlns:pssapi="http://tempuri.org/object" >
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:title>my title</pss:title>
        <pss:link>http://tempuri.org/object</pss:link>
        <pss:description>some content</pss:description>
        <pss:guid>http://tempuri.org/guid</pss:guid>
      </pss:item>
    </pssapi:editItem>
  </soap:Body>
</soap:Envelope>

deleteItem

Deleting an existing item in an RSS feed, has the meaning of removing the item from the RSS data source.

Request

A sample pssapi.deleteItem request follows.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
  xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" >
  <soap:Header>
    <wsse:Security> 
      <wsse:UsernameToken> 
        <wsse:Username>randy</wsse:Username> 
        <wsse:Password>hello</wsse:Password> 
      </wsse:UsernameToken> 
    </wsse:Security>   
  </soap:Header>
  <soap:Body>
    <pssapi:deleteItem xmlns:pssapi="http://tempuri.org/object" >
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:guid>http://tempuri.org/guid</pss:guid>
      </pss:item>
    </pssapi:deleteItem >
  </soap:Body>
</soap:Envelope>

Response

A sample pssapi.deleteItem response follows. Note, the response is an echo of the request without the authentication module in the header. The response may add or change elements to fit the data sources specific RSS flavor. For instance, if the source was implementing RSS 0.91 or RSS 1.0, the items could change in style drastically.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" >
  <soap:Body>
    <pssapi:deleteItem xmlns:pssapi="http://tempuri.org/object" >
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:guid>http://tempuri.org/guid</pss:guid>
      </pss:item>
    </pssapi:deleteItem >
   </soap:Body>
</soap:Envelope>

Notes

Please note that although I include only one method in each each example, there is not limitation to one method call per request. Theoretically, you could have a mix of newItem, editItem and deleteItem methods in each request. You can also have more than one of each request type.

  <soap:Body>
    <pssapi:newItem xmlns:pssapi="http://tempuri.org/object" >
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:title>mytitle</pss:title>
        <pss:link>http://tempuri.org/object</pss:link>
        <pss:description>mytitle</pss:description>
      </pss:item>
    </pssapi:newItem>
    <pssapi:editItem xmlns:pssapi="http://tempuri.org/object" >
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:title>My Title</pss:title>
        <pss:link>http://tempuri.org/object</pss:link>
        <pss:description>some content</pss:description>
        <pss:guid>http://tempuri.org/guid</pss:guid>
      </pss:item>
    </pssapi:editItem>
  </soap:Body>

Within each method request, you could also have more than one item. This allows the programmer to add, edit or delete multiple items per method request.

  <soap:Body>
    <pssapi:newItem xmlns:pssapi="http://tempuri.org/object" >
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:title>mytitle</pss:title>
        <pss:link>http://tempuri.org/object</pss:link>
        <pss:description>mytitle</pss:description>
      </pss:item>
      <pss:item xmlns:pss="http://duderesearch.com/archives/000010.html" >
        <pss:title>My Title</pss:title>
        <pss:link>http://tempuri.org/object</pss:link>
        <pss:description>some content</pss:description>
      </pss:item>
    </pssapi:newItem>
  </soap:Body>

Note also that you are not limited to the four basic elements of an RSS item; title, link, description and guid. You can also use any of the other elements; pubDate, category, etc. You can also include elements from many of the extensions like trackbacks and the comment api.

RSS Flavors

It is not advised to use PSSAPI with obsolete flavors of RSS like version 0.91 and version 1.0. Incompatibilities in the data set make programmatic control cumbersome with these version of RSS. It is also strongly advised against using funky RSS with PSSAPI.

Pie/Echo

Assuming Pie/Echo makes it to adoption, then this document applies equally to this format. Only samples are provide as Pie/Echo is still far from complete. Even the example should only be considered for form and not content as the element of Pie/Echo are in a lot of flux.

I was originally going to write this solely for RSS, but decided that it was trivial enough to add support for Pie/Echo.

newItem

Request

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"  
	xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" >
  <soap:Header>
    <wsse:Security>
      <wsse:UsernameToken>
        <wsse:Username>randy</wsse:Username>
        <wsse:Password>hello</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    <pssapi:newItem xmlns:pssapi="http://tempuri.org/object" >
      <pie:entry xmlns:pie="http://tempuri.org/object" >
        <pie:title>My Title</pie:title>
        <pie:link>http://tempuri.org/object</pie:link>
        <pie:content type="text/html" >some content</pie:content >
      </pie:entry>
    </pssapi:newItem>
  </soap:Body>
</soap:Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" >
  <soap:Body>
    <pssapi:newItem xmlns:pssapi="http://tempuri.org/object" >
      <pie:entry xmlns:pie="http://tempuri.org/object" >
        <pie:title>My Title</pie:title>
        <pie:link>http://tempuri.org/object</pie:link>
        <pie:content type="text/html" >some content</pie:content >
      </pie:entry >
    </pssapi:newItem>
  </soap:Body>
</soap:Envelope>

editItem

Request

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
  xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" >
  <soap:Header>
 </soap:Header>
  <soap:Body>
    <pssapi:editItem xmlns:pssapi="http://tempuri.org/object" >
      <pie:item xmlns:pie="http://tempuri.org/object" >
        <pie:title>my title</pie:title>
        <pie:link>http://tempuri.org/object</pie:link>
        <pie:content type="text/html" >some content</pie:content >
      </pie:item>
    </pssapi:editItem>
  </soap:Body>
</soap:Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" >
  <soap:Body>
    <pssapi:editItem xmlns:pssapi="http://tempuri.org/object" >
      <pie:item xmlns:pie="http://tempuri.org/object" >
        <pie:title>my title</pie:title>
        <pie:link>http://tempuri.org/object</pie:link>
        <pie:content type="text/html" >some content</pie:content >
      </pie:item>
    </pssapi:editItem>
  </soap:Body>
</soap:Envelope>

deleteItem

Request

A sample pssapi.deleteItem request follows.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
  xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" >
  <soap:Header>
    <wsse:Security> 
      <wsse:UsernameToken> 
        <wsse:Username>randy</wsse:Username> 
        <wsse:Password>hello</wsse:Password> 
      </wsse:UsernameToken> 
    </wsse:Security>   
  </soap:Header>
  <soap:Body>
    <pssapi:deleteItem xmlns:pssapi="http://tempuri.org/object" >
      <pie:item xmlns:pie="http://tempuri.org/object" >
        <pie:link>http://tempuri.org/guid</pie:link>
      </pie:item>
    </pssapi:deleteItem >
  </soap:Body>
</soap:Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" >
  <soap:Body>
    <pssapi:deleteItem xmlns:pssapi="http://tempuri.org/object" >
      <pie:item xmlns:pie="http://tempuri.org/object" >
        <pie:link>http://tempuri.org/guid</pie:link>
      </pie:item>
    </pssapi:deleteItem >
   </soap:Body>
</soap:Envelope>

Motivation

I've always been an RSS and SOAP fan. I recently implemented BloggerAPI and MetaWeblogAPI and found them cumbersome. I don't think the average programmer stands a chance with XML-RPC. Beyond that neither API is complete and only recently MetaWeblogAPI provided supported for deleting items (BloggerAPI simply doesn't). Then half way thru writing this, Jon Udell called for a SOAP blogging protocol. That was fait accompli.

Changes

• July 10 2003 - replaced BasicAuth with UsernameToken, fixed errors in Fault Response, added Pie/Echo