This is the official place for BRAX API documentation. The acronym B.R.A.X., stands for the Bordom RPC API over XML. It is a specification for a web publishing system delivered over XML-RPC. It can easily be compared to other APIs, such as the MetaWeblogAPI, BloggerAPI, MovableTypeAPI, and others. It is an extended version of these existing APIs. After examination of the existing APIs, BRAX was developed as an alternative, to achieve a level of flexibility and granularity that the other systems do not offer. BRAX was originally concepted to serve the specific need of providing a common interface for editing bordom.net. The goal of BRAX is to provide a flexible web service API for bordom.net, with the idea that it can and may evolve into a full-fledged, general-purpose web service API for other systems. For a full list of API methods, see system.listMethods.

Table of Contents BRAX Overview Authentication Usage / Examples

The API aims to provide a complete layer between your application and the database on bordom.net. There are many commands available which facilitate the publishing of content on bordom.net.

Below is a simplified diagram illustrating the BRAX layer between your application and bordom.net.

The BRAX API is available at http://api.bordom.net. It only accepts HTTP POST transport requests. Before you will be able to communicate with BRAX, you will first need to authenticate with a given username and password.

Each client that is designed to communicate with the BRAX API must authenticate itself using a BRAX "source". Many clients may share the same source - this is expected.

For example, the users of the IRC channel #bor use the BordomIRC client to communicate with bordom.net. In the future, there will likely be a desktop agent for MacOSX. Both of these clients are utilitizing the same content on bordom.net. Therefore, both of these clients will authenticate using the same BRAX "source".

A source is term that describes a content supplier. This can be a group of people, or just a single person. These are details that are defined by the BRAX clients. To the BRAX server, it only cares which source is associated to the content being manipulated.

Sources are authenticated using an HTTP username and password. All XML_RPC invocations will require these credentials be set or a 401 HTTP error will be returned. At this time, access to the BRAX API is private. (See us in efnet #bor)

All BRAX commands are served over XML_RPC, so the invocations of these commands are performed very similiar to each other. The examples used in this document are written in PHP, and using the PEAR XML_RPC library.

Retrieving a Single Item

getItem( int $item_id )

Retrieving a set of Items

getItems( struct $params )

The following params are supported:

• query: If query param is specified, it limits the returned results to those items that match the given query phrase. This is most often used in searches.
• nick: The nick param limits the returned results to those items matching the given nick. This is used when you want to search by author.
• tag: Only return results that have the specified tag word.
• page: Page number to return. By default, page 1 is returned.
• source: Limit results to a those originating from a particular source. (such as channel #bor only)
• type: Type of items (audio, videos, documents, images)

Adding a New Item

addItem( string $author, string $url, [string $title] )

Below is an example of authenticating with BRAX (using the source "test" from ruby, and adding a new item.

#!/usr/bin/ruby
require 'xmlrpc/client'

server = XMLRPC::Client.new2("http://test:testrpc@api.bordom.net/")
server.call("addItem",
        "testmeok", # author's nickname
        "http://linuxbrit.co.uk/rbot/", # submitted url
        "" # optional item title
)

Updating an Existing Item

updateItem( int $item_id, struct $params )

Tagging

Tag words may only contain certain characters. Namely, no punctuation or extended (unsafe) characters are accepted in a tag word. Tag words are stripped of all non-alphanumeric characters - however spaces ARE allowed.

addTag( int $item_id, string $tag )
deleteTag( int $item_id, string $tag )

Commenting

addComment( int $item_id, string $author, string $comment )
deleteComment( int $comment_id )
getComment( int $comment_id )

For a full list of API methods, see system.listMethods.