Jaconda API Documentation

Ruby hacker? Download the official jaconda gem.

Jaconda provides easy access to all your data via an XML and JSON-based, RESTful API.

This documentation describes how to manage Rooms, Members, Uploads and Messages on behalf of the authorized user.
If you only want to send notifications to your rooms, read Jaconda Notifications guide instead.

Requests

All API calls will be made against the domain that your account is accessed from. For instance, if you want to get a list of all rooms for the bigbang account, you should access https://bigbang.jaconda.im/api/v2/rooms.xml. The docs will only show the relative path starting from the first slash.

Jaconda API 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 authenticated.

Jaconda allows three forms of authentication. The preferred method is to use HTTP Basic Authentication with API token as the username, and "X" (or some otherwise bogus text) as the password (only the API token is used). When logged in, your API token can be found on the "My Info" page.
Example:

$ curl -u J4c0nd4_p0w4hub3r4l13s:X https://bigbang.jaconda.im/api/v2/rooms.xml

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

$ curl https://bigbang.jaconda.im/api/v2/rooms.xml?_token=J4c0nd4_p0w4hub3r4l13s

Also Jaconda API supports HTTP Basic Authentication with email and password.
Example:

$ curl -u sheldon@bigbang.caltech.edu:secret https://bigbang.jaconda.im/api/v2/rooms.xml

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+from+api' https://bigbang.jaconda.im/api/v2/rooms/support/messages.xml

Example with xml as a body:

$ curl -u api_token:x -H 'Content-Type: application/xml' -d '<message><text>Hello with xml</text></message>' https://bigbang.jaconda.im/api/v2/rooms/support/messages.xml

Example with json as a body:

$ curl -u api_token:x -H 'Content-Type: application/json' -d '{message: {text: "Hello with json"}}' https://bigbang.jaconda.im/api/v2/rooms/support/messages.xml

Note that responses in above examples will be in xml, because url is followed by .xml

Responses

Success responses

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

Failure responses

If request fails, the server will respond with failure code and message. There are several possible failure responses:
400 - the request can't be processed due to invalid format or auth type - supported response formats are XML and JSON, supported authentication methods are HTTP Basic and parameter-based
401 - unauthorized access - ensure that API key is correct
404 - the requested resource cannot be found - ensure that resource ID 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 response will have a root element "errors" with one or more "error" children, describing each error that occurred.
The JSON response 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

Members

Messages

Rate limiting

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