Unfuddle API: Introduction

Introduction top

The Unfuddle API, currently in public BETA, provides developers with a very simple medium for creating new Unfuddle-based applications or integrating Unfuddle with their existing development workflow. It offers direct access to practically all the features of your Unfuddle acount.

The Unfuddle API is completely RESTful and is implemented as XML over HTTP. Authentication is performed using HTTP Basic Authentication. Please note that access to the Unfuddle API is strictly limited by both the featureset of your Unfuddle account as well as the permissions of the person being used to access the Unfuddle API.

Throughout this documentation, all examples will be given using the command line tool "curl". However, any HTTP library or client could be used to connect to the Unfuddle API. For examples using other libraries, please see the Examples section of the documentation.

Request Format top

URLs

The URL format for all Unfuddle API requests is always very similar. All URLs will always begin as follows, where mysubdomain is your Unfuddle account subdomain:

http://mysubdomain.unfuddle.com/api/v1/...

or for accounts with support for SSL:

https://mysubdomain.unfuddle.com/api/v1/...

HTTP Methods

Request to the Unfuddle API are made using four standard HTTP methods, each one carrying a specific connotation:

Request Body

In the case that a request to the Unfuddle API requires information to be sent via the request body, all request body data must be sent using XML. For example, a typical POST would have the following format:

curl -i -u username:password -X POST \
  -H 'Accept: application/xml' \
  -H 'Content-Type: application/xml' \
  -d '<request-body-formatted-as-xml/>' \
  http://mysubdomain.unfuddle.com/api/v1/...

Optional Parameters

Often, the result of a call to the Unfuddle API can be altered by providing parameters. These parameters can be different depending on the resource and are documented along with the resource in question.

Parameters can always be passed in one of two ways: via the query string or as XML in the request body. A request can also have a mix of parameters in both the request body and query string, with the query string taking precedence in the case of duplicates.

All parameters in the documentation are shown in XML only. Note that the XML versions of parameter names often contain dashes as a matter of convention. If a parameter is passed to a resource via the query string, it must contain underscores rather than dashes.

formatted=true

There is one globally available query string parameter for all XML and JSON resources: "formatted=true". This parameter forces the output of the Unfuddle API to include a formatted version of any fields that would typically contain markdown/textile, a date, or a time. The formatted versions are available as "fieldname-formatted".

curl -i -u username:password -X PUT \
  -H 'Accept: application/xml' \
  http://mysubdomain.unfuddle.com/api/v1/projects/4598/messages/54585.xml?formatted=true
  
<?xml version="1.0" encoding="UTF-8"?>
<message>
  ...
  <body> <!-- the unformatted body --> </body>
  <body-formatted> <!-- the formatted body --> </body-formatted>
  ...
  <created-at> <!-- the time in server time --> </created-at>
  <created-at-formatted>
    <!-- the time formatted as text and in the time zone of the requesting person -->
  </created-at-formatted>
  ...
</message>

Regardless of the model, fields named "created-at" or "udpated-at" will be formatted if formatted=true. For more information about other model-specific fields that will be formatted, please see the documentation for specific Data Models.

Response Format top

Response Formats

If the response from the API contains a body, you can often specify the response format. This will typically be XML or JSON for most resources, however, you can often specify other formats depending on the desired resource. Some of the most frequent formats that can be returned are as follows:

  • XML (application/xml)
  • JSON (application/json)
  • RSS (application/rss+xml)
  • ICS (text/calendar)
  • TGZ (application/x-gzip)

HTTP Status Codes

The following HTTP status codes are used in the responses to indicate the nature of the response.

Dates and Times

Note that regardless of the response format (i.e. XML, JSON, etc.), all times will be reported in the preferred time zone of the requesting user.

Collections and Empty Sets top

Certain requests to the Unfuddle API will render a collection of objects. If the output format is XML, note that the objects will be returned in a parent tag that is the plural of the object type. For instance, if you were expecting a list of people in an account, the XML would similar to the following:

<?xml version="1.0" encoding="UTF-8"?>
<people>
  <person> ... </person>
  <person> ... </person>
  ...
</people>

If the collection of objects is empty, then the following may be returned:

<?xml version="1.0" encoding="UTF-8"?>
<nil-classes>
</nil-classes>

Of course, the relevant data type may also be used to represent an emtpy set:

<?xml version="1.0" encoding="UTF-8"?>
<messages>
</messages>

Errors top

When an error has occurred, the HTTP status code will be representative of the type of error that occurred. In addition, the API will often return a list of errors as XML in the response body. For example:

HTTP/1.1 400 Bad Request
Status: 400 Bad Request
Content-Type: application/xml; charset=utf-8
...

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>First name cannot be blank</error>
</errors>