BitWorking

A Side-by-side comparison with the CommentAPI

Sam Ruby has a proposal for a SOAP-based alternative to the CommentAPI. To try to clarify things here is an example interaction for each proposal, starting with Sam's.

First, here is the message sent to the end-point:

POST /news/comments/5 HTTP/1.1
Content-Type: text/xml

<?xml version="1.0"?>
<soap:Envelope 
  xmlns:dc="http://purl.org/dc/elements/1.1/" 
  xmlns:content="http://purl.org/rss/1.0/modules/content/"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns="http://purl.org/rss/1.0/">
  <soap:Header/>
  <soap:Body>

    <item rdf:about="http://www.intertwingly.net/blog/1290.html">
      <title>Would you? Could you?</title>
      <link>http://www.intertwingly.net/blog/1290.html</link>
      <description>Before reading this, please read this.</description>
      <content:encoded>Before reading
           &lt;a href="http://www.intertwingly.net/blog/1290.soap"&gt;this&lt;/a&gt;, please read
           &lt;a href="http://enquirer.com/editions/2002/01/27/tem_sam_(i_am)_has.html"&gt; this&lt;/a&gt;.
      </content:encoded>
      <dc:date>2003-03-20T12:49:50-05:00</dc:date>
    </item>

  </soap:Body>
</soap:Envelope>

This is a best guess at what the response generated would be. The actual response may differ from this, corrections are welcome.

HTTP/1.1 200 OK

<?xml version="1.0"?>
<soap:Envelope 
  xmlns:dc="http://purl.org/dc/elements/1.1/" 
  xmlns:content="http://purl.org/rss/1.0/modules/content/"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns="http://purl.org/rss/1.0/">
  <soap:Header/>
  <soap:Body>

    <item/>

  </soap:Body>
</soap:Envelope>

Now here is the same interaction using the CommentAPI.

POST /news/comments/5 HTTP/1.1
Content-Type: text/xml

<?xml version="1.0"?>
<item xmlns:dc="http://purl.org/dc/elements/1.1/" >
  <title>Would you? Could you?</title>
  <link>http://www.intertwingly.net/blog/1290.html</link>
  <description>Before reading this, please read this.</description>
  <content:encoded>Before reading
       &lt;a href="http://www.intertwingly.net/blog/1290.soap"&gt;this&lt;/a&gt;, please read
       &lt;a href="http://enquirer.com/editions/2002/01/27/tem_sam_(i_am)_has.html"&gt; this&lt;/a&gt;.
  </content:encoded>
  <dc:date>2003-03-20T12:49:50-05:00</dc:date>
</item>

And this is the response:

HTTP/1.1 200 OK
To be fair, Sam's version has two more pieces of information (a plaintext excerpt, and a date).

Posted by Mark on 2003-03-21

Yeah, but what's the point of the date? As for the plaintext version, since markup can be stripped to effectively give the same thing, is there any value in that?

Posted by Seairth on 2003-03-21

My excerpts are not the same as a stripped version of my markup; I hand-write custom excerpts. This matters more for notifications than for posting comments. Including the date allows for the possibility of batch processing (user is offline, writes a bunch of comments to various blog entries their aggregator has downloaded, then sends all the comments once the user comes back online). Could also be useful for batch processing notifications.

Posted by Mark on 2003-03-22

Mark, That does bring up a good point, as to what are required and optional elements. I was following the RSS 2.0 specification in which only one of 'title' or 'description' are required. So yes, content:encoded and dc:date could have been included in CommentAPI example. Just like for aggregators now, it would be up to the receiver of a comment to pick which element to use. As for the utility of dc:date, that would depend on the interpretation, is the date when the comment was sent, or the date when it was received? Posting comments across different timezones will give you different values for dc:date.

Posted by Joe on 2003-03-22

Joe, I know you know that everything is optional in RSS (except the BLINK tag). My only point was that the comparison is not quite fair because you're not quite comparing apples to apples. So do it; you'll still win on simplicity. Sam will try to say "well, it's just a little extra, and it's boilerplate, and you can ignore it on receipt, or whatever" and you'll say "that's just what the RSS 1.0 folks said about RDF/XML" and he'll no doubt say something else. As for dates, a dc:date can include a timezone (your example does, although it's formatted wrong, there should be no colon in the timezone part), so where's the ambiguity?

Posted by Mark on 2003-03-24

Done, though I haven't updated the timezone part: http://www.w3.org/TR/NOTE-datetime I know I used to have a validation problem with my RSS feed for providing the timezone down to the seconds which is incorrect, but specifying the timezone down to the minute is ok.

Posted by Joe on 2003-03-24

Indeed. I stand corrected.

Posted by Mark on 2003-03-24

I don't get the purpose of the XML stuff. Surely a good old standard form POST do the job just as well?

Posted by anonymous on 2003-04-14

<h1>Please check some relevant pages about- Tons of interesdting stuff!!! </h1>

Posted by anonymous on 2004-12-01

2003-03-21