"This is the most logical API I've ever worked with", - happy developer.

Jaconda provides easy access to all your data via an XML and JSON-based, RESTful API.
This includes managing Rooms, Users and Messages. Each resource will typically have a GET request to list records (GET /rooms.xml), and a GET request to list a specific record (GET /rooms/1.xml). POST requests are used to create new records (POST /rooms.xml). Use PUT requests to update a resource (PUT /rooms/1.xml). Finally, use DELETE request to destroy a resource (DELETE /rooms/1.xml).

Requests

Jaconda API currently supports 2 formats: XML and JSON. That means that the URL in each request should be followed by .xml or .json.

Authentication

Every request to Jaconda API must be authorized with API token.
When logged in, your API token can be found on the "Account" page.

Jaconda allows two forms of authentication. The first is HTTP Basic Authentication (preferred), using your API token as the username, and "X" (or some otherwise bogus text) as the password (only the API token is used for authenticating API requests).
Example with cURL:

$ curl -u J4c0nd4_p0w4hub3r4l13s:X http://jaconda.im/api/rooms.xml

The second form of authentication is appending a _token parameter to your requests.
Example with cURL:

$ curl http://jaconda.im/api/rooms.xml?_token=J4c0nd4_p0w4hub3r4l13s

Parameters

POST and PUT parameters can be transmitted in 3 ways: plain text, xml and json.
For xml and json requests, you should specify appropriate Content-Type header.
Regardless the format, parameters should be encapsulated in an appropriate array.
Example with plain parameters:

$ curl -u api_token:x -d 'message[text]=Hello' http://jaconda.im/api/rooms/1/messages.xml

Example with xml as a body:

$ curl -u api_token:x -H 'Content-Type: application/xml' -d '<message><text>Hello from xml</text></message>' http://jaconda.im/api/rooms/1/messages.xml

Example with json as a body:

$ curl -u api_token:x -H 'Content-Type: application/json' -d '{message: {text: "Hello from json"}}' http://jaconda.im/api/rooms/1/messages.xml

Note that in all this examples response would be in xml, because url is followed by .xml

Responses

Success responses

The server will respond with a 200 OK response if there is no errors. The response body will contain requested resource or resources.

Failure responses

If a request fails, the server will respond with a failure code and message. There are several possible failure responses:
400 - the request can't be processed due to invalid format or auth type - API supports XML and JSON requests with HTTP Basic authentication
401 - unauthorized access - ensure that API key is correct
422 - the submitted data was invalid - check the corresponding error messages
500 - unexpected errors - submit a bug report at http://help.jaconda.im

The response body for 422 failure will contain description of the error.
The XML will have an errors root element with one or more error children, describing each error that occurred.
The JSON will have array of one or more errors, describing each error that occurred.

Methods

The API supports the following methods to send and receive data.

Rooms

• GET rooms - Retrieves a list of rooms of the authenticated account.
• GET room - Shows the specified room identified by its integer id.
• POST room - Creates a new room for the authenticated account.
• PUT room - Updates the room identified by its integer id.
• DELETE room - Deletes the room identified by its integer id.

Users

• GET users - Retrieves a list of users in the specified room.
• GET user - Shows the specified user identified by its integer id.
• POST user - Invites a new user to the room.
• PUT user - Updates the user identified by its integer id.
• DELETE user - Deletes the user identified by its integer id.

Messages

• GET messages - Retrieves a list of messages in the specified room.
• GET message - Shows the specified message identified by its integer id.
• POST message - Broadcasts a new message in the room.

Rate limiting

There is no rate limiting yet, but this may change in the future. Please check the API Changelog for further changes.