RFC: PSSAPI 0.9 (early draft)

[Randy Charles Morin]

comments here
http://www.kbcafe.com/iblogthere4im/comments.aspx?guid=20030709143822

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>
<wsseassword>hello</wsseassword>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
<soap:Body>
<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>
<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>
<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>
<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>
<wsseassword>hello</wsseassword>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
<soap:Body>
<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>
<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>
<pss:title>mytitle</pss:title>
<pss:link>http://tempuri.org/object</pss:link>
<pss:description>mytitle</pss:description>
</pss:item>
</pssapi:newItem>
<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>
<pss:title>mytitle</pss:title>
<pss:link>http://tempuri.org/object</pss:link>
<pss:description>mytitle</pss:description>
<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>
<wsseassword>hello</wsseassword>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
<soap:Body>
<pssapi:newItem xmlnsssapi="http://tempuri.org/object" >
<pie:entry xmlnsie="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 xmlnsssapi="http://tempuri.org/object" >
<pie:entry xmlnsie="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 xmlnsssapi="http://tempuri.org/object" >
<pie:item xmlnsie="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 xmlnsssapi="http://tempuri.org/object" >
<pie:item xmlnsie="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>
<wsseassword>hello</wsseassword>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
<soap:Body>
<pssapi:deleteItem xmlnsssapi="http://tempuri.org/object" >
<pie:item xmlnsie="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 xmlnsssapi="http://tempuri.org/object" >
<pie:item xmlnsie="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

 

[Andy Dingley]

Where's the RSS vs. Echo bunfight happening these days ?

I know nothing of Echo - just haven't had the time to catch up.
You'll probably know my attitude to Dave Winer and RSS 2. I'm
surprised (a little) if Aaron is now backing Echo.

I understand the idea behind Echo - but "the community wetware is
broken and has produced too many versions, lets fix this by
introducing yet another one" is a crazy idea. Assassination - it's
the only way to control the RSS standards explosion.



When I last looked (briefly) at Echo, it was still very much a product
of people who didn't understand _why_ RSS 1.0 was so much better.
(Google this group - I'm sure I've posted about it) As a result,
they're heading towards something that still can't do as much.

If you want the future extensibility to be comparable to RSS 1.0, then
you _need_ the RDF data model, not XML. It's not hard to use for the
minimal case, for goodness sake !