Simple Blogging API

RFC???? (Drafting RFC document)

Author: Chris Stranex <sbapi@sa.web.za>


Introduction

SBAPI (Simple Blogging API) is a XML-based document format that serves as an API to aid weblog software communicate more effeciently with other weblog or similar software.

The primary use case that SBAPI addresses is the need for a simple common standard for weblog software to communicate in an effecient way.

Examples

Example 1
A simple SBAPI request to find out information about the website.
<?xml version="1.0" encoding="utf-8"?>
<sbapi version="1.0" xmlns="http://sbapi.sourceforge.net/#ns">
   <auth>
      <username>example</username>
      <password hash="sha256">50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c</password>
   </auth>

   <action do="site.getInformation">
      <null/>
   </action>
</sbapi>
Example 2
A more complicated SBAPI request to create a news / weblog post on the website.
<?xml version="1.0" encoding="utf-8"?>
<sbapi version="1.0" xmlns="http://sbapi.sourceforge.net/#ns">
   <auth>
      <username>example</username>
      <password hash="sha256">50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c</password>
   </auth>

   <action do="posts.createNew">
      <title>An example website post</title>
      <id>new()</new>
      <date>now()</date>
      <categories>uncategorised()</categories>
      <post type="plaintext">This is an example post on the example website</post>
   </action>
</sbapi>

XML Namespace

The XML Namespaces URI [W3C.REC-xml-names-19990114] for the XML data format described in this specification is:

    http://sbapi.sourceforge.net/#ns

SBAPI Documents

This specification describes two types of SBAPI documents: SBAPI Request Documents and SBAPI Response Documents

An SBAPI Request Document is a document sent from a weblog client to a weblog 'server'. The server parses the request and issues a SBAPI Response Document which is given to the client.

A SBAPI Reponse Document either is an error document or a success document.

Text Constructs

Text in the SBAPI document is human-readable text. The contents in language sensitive and may be plaintext , html or xhtml. The default character encoding for text is UTF-8

A text construct may be present in one of the following elements:
<data></data>
<post></post>
<title></title>
<description></description>

The post tag must have the type attribute. The value must be one of the following: 'html' , 'xhtml' or 'plaintext'.

HTML and XHTML

if the 'html' or 'xhtml' types are used the data sent must be able to be entered directly into a div element without modification. HTML elements must not be escaped.

Example of valid HTML content:
<post type="xhtml">Some <strong>example</strong> text</post>
Example of valid HTML content with CDATA:
<post type="xhtml"><![CDATA[<div>An example using <strong>CDATA</strong> with html content.</div>]]></post>

Date Constructs

A date construct is any element that uses dates. The date format used in SBAPI is IS0 8601 (YYYY-MM-DD hh:mm:ss). All times are assumed to be UTC.

Example of a date
<date>2006-02-04 15:39:56</date>

A date may also be specified as now(). Now() means to use the server's date and time at the time the server reiceved the SBAPI Request Document.

Example of a date with now()
<date>now()</date>

Would be: 2006-02-04 15:39:56 at the server

Category Constructs

A category construct is any element that uses a semi-colon to seperate values.

Example of a category
<categories>general;international;computers;internet</categories>

A category can also be specified as uncategorised() or uncategorized() which means it is assigned to no category.

Example of an uncategorised category
<categories>uncategorised()</categories>

SBAPI Element

The sbapi element contains the entire SBAPI Request and Response Document. The sbapi element is required.

Auth Element

The auth element contains information to authenticate itself with the server. The element and its children are only required for SBAPI Request Documents. The sbapi element is required.

Username Element

The username element contains the username to authenticate the document with. Usernames are plaintext only. The username element is required.

Password Element

The password element contains the password to authenticate the document with. Passwords must be hashed. The cannot be plaintext. The password element is required.

The 'hash' attribute is used to tell the server what type of hash is being used. Supported hashes are: 'sha256','gost','tiger128'. The default hash is 'sha256'. The 'hash' attribute is required.

Example of the auth element
<auth>
   <username>example</username>
   <password type="sha256">50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c</password>
</auth>

Action Element

The action element is contains a request's data. The element is only required for SBAPI Request Documents.

The 'do' attribute is used to tell the server what action it must perform. Supported values are:

posts prefix:
"posts.createNew" - Create a new entry / post
"posts.updateExisting" - Edit an existing entry / post
"posts.deleteExisting" - Delete an existing entry / post
"posts.countExisting" - Count the number of existing posts
"posts.getExisting" - Get an existing entry / post

site prefix:
"site.getInformation" - Retrieve information about the website.
"site.getCategories" - Retrieve a list of categories used on the website.
Requirements

The following elements are required for posts.createNew , posts.updateExisting , posts.deleteExisting:

The following elments are required for posts.countExisting , site.getInformation , site.getCategories:

site.getInformation
site.getInformation must return data about the website. The following data is required to be sent:
<xml:site.name>Website Name</xml:site.name>
<xml:site.url>Website URL</xml:site.url>
<xml:site.language>Website Language</xml:site.language>
<xml:site.description>Website Description</xml:site.description>
<xml:site.currentID>ID of last entry</xml:site.currentID>
<xml:site.preferredHash>The prefered hash</xml:site.preferredHash>
<xml:site.preferredData>The prefered type of post (xhtml,html,plaintext)</xml:site.preferredData>

Other information may be sent. It must be prefixed: xml:site.

At one or more of the following elements are required for posts.getExisting:

The action element may contain only one 'do' attribute. It may only contain one of each of the elements below:

Title Element

The title element is plaintext. It is used either to search for an entry / post (eg: posts.updateExisting) or to set the title of an entry / post (eg: poss.createNew).

Date Element

The date element uses a date construct. It is used either to search for an entry / post or to set a new entries date.

ID Element

The id element is a string or an integar. It is used either to search for an entry / post or to set a new entry / post. The ID element can also be "new()". This means the server must assign it its own id.

Categories Element

The categories element uses a category construct. It is used to show what categories or tags the post belongs to.

Post Element

The post element uses a text construct. It contains the main content of the entry / post.

Limit Element

The limit element is an integar. It contains a limit to the number of returned results for the posts.getExisting action

Null element

The null element is used when an action has no parameters.

Example of the action element
<action do="posts.createNew">
   <title>example></title>
   <date>now()></date>
   <id>new()></id>
   <categories>example;news></categories>
   <post type="xhtml">Test post using SBAPI</post>
</action>

Response Element

The response element is used only for SBAPI Response Documents. It is required.

Error Element

The error element is an integar. The value is either 0 (no error) or 1 (error). If the value is 1 then the description element is required.

Description Element

The description element is a text construct. It is used when an error is generated by the server. It describes the error to the client.

Data Element

The data element can be a parent element or a text construct. It is used when the server needs to pass informtion to the client when there is no error.

The data element can contain any number of elements which must be prefixed xml:. Because of this the data element has one attribute , an XML namespace.

Example of an error response:
<response>
   <error>1</error>
   <description>Some error here>/description>
</response>
Example of a success response:
<response>
   <error>0</error>
</response>
Example of a response with returned data:
<response>
   <error>1</error>
   <data>Some info here</data>
</response>
Example of a response with XML data:
<response>
   <error>1</error>
   <data xmlns:xml="http://www.w3.org/1999/xhtml">
      <xml:info>
         <xml:name>Bobby</name>
      <xml:info>
   </data>
</response>

Document Headers

The following HTTP headers are required to be sent when sending a SBAPI Request Document:
User-Agent: USER-AGENT
Accept-Charset: CHARSET
Content-Type: application/xml

The following HTTP headers are required to be sent when sending a SBAPI Response Document:
Content-Type: text/xml; charset=CHARSET

Examples

Requesting Site Information (SBAPI Request Doucment)
<?xml version="1.0" encoding="utf-8"?>
<sbapi version="1.0" xmlns="http://sbapi.sourceforge.net/#ns">
   <auth>
      <username>example</username>
      <password hash="sha256">50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c</password>
   </auth>

   <action do="site.getInformation">
      <null/>
   </action>
</sbapi>
Responding with Site Information (SBAPI Response Document)
<?xml version="1.0" encoding="utf-8"?>
<sbapi version="1.0" xmlns="http://sbapi.sourceforge.net/#ns">
   <response>
      <error>0<error>
      <data xmlns:xml="http://www.w3.org/1999/xhtml">
         <xml:site.name>Some website</xml:site.name>
         <xml:site.url>http://www.example.com/</xml:site.url>
         <xml:site.language>en-GB</xml:site.language>
         <xml:site.description>A typical example website</xml:site.description>
         <xml:site.currentID>9</xml:site.currentID>
         <xml:site.preferredHash>sha256</xml:site.preferredHash>
         <xml:site.preferredData>xhtml</xml:site.preferredData>
         <xml:misc.authorEmail>example@example.com</xml:misc.authorEmail>
      </data>
   </response>
</sbapi>
Requesting posts.countExisting (SBAPI Request Document)
<?xml version="1.0" encoding="utf-8"?>
<sbapi version="1.0" xmlns="http://sbapi.sourceforge.net/#ns">
   <auth>
      <username>example</username>
      <password hash="sha256">50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c</password>
   </auth>

   <action do="posts.countExisting">
      <null/>
   </action>
</sbapi>
Responding with entries (SBAPI Response Document)
<?xml version="1.0" encoding="utf-8"?>
<sbapi version="1.0" xmlns="http://sbapi.sourceforge.net/#ns">
   <response>
      <error>0<error>
      <data>9</data>
   </response>
</sbapi>
Sending a SBAPI Request Document with an error
<?xml version="1.0" encoding="utf-8"?>
<sbapi version="1.0" xmlns="http://sbapi.sourceforge.net/#ns">
   <action do="posts.countExisting">
      <null/>
   </action>
</sbapi>
Responding with an error (SBAPI Response Document)
<?xml version="1.0" encoding="utf-8"?>
<sbapi version="1.0" xmlns="http://sbapi.sourceforge.net/#ns">
   <response>
      <error>1<error>
      <description>No Authentication Information!</description>
   </response>
</sbapi>

Copyright and Disclaimer

This document and translations of it may be freely distributed to others. It may be copied, published and distributed in whole or in part, without restriction of any kind, provided that the copyright notice for this document and these paragraphs are included in all such copies and derivative works.

This document may not be modified in any way, such as by removing the copyright notice or references to the original author. No claim of ownership is made to the format of what the document describes even though the copyright restrictions apply to the written document's specification. Any party, for commercial or non-commercial purposes, use this format wihout any royalty or licencing fee to the author. The limited permissions granted are perpetual and will not be revoked by the author or their successors or assigns.



(c) 2006 Chris Stranex. All Rights Reserved.
Valid XHTML 1.0 Strict