Unfuddle STACK API

Usage Scenarios

Reference

Introduction

Introduction

The STACK API 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 account.

The STACK API is completely RESTful and is implemented as XML over HTTP. Authentication is performed using HTTP Basic Authentication. Please note that access to the STACK 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 STACK 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 STACK API. For examples using other libraries, please see the Examples section of the documentation.

Request Format

URLs

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

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

or for accounts with support for SSL:

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

HTTP Methods

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

GET Considered a "safe" method as any requests to the STACK API with an HTTP GET are non-volatile and will not change any values within your Unfuddle account.
POST Generally used when creating a new object on a collection.
PUT Used to update an already existing object.
DELETE Generally used to permanently delete an already existing object within your account. However, there are circumstances where a DELETE will simply change the state of an object. For example, deleting a Person will actually permanently mark that Person as removed, but they are never actually deleted.

Request Body

In the case that a request to the STACK 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/>' \\
  https://mysubdomain.unfuddle.com/api/v1/...

Optional Parameters

Often, the result of a call to the STACK 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 STACK 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' \\
  https://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 "updated-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

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.

200 OK Indicates that the request was successful.
400 Bad Request The request body was malformed or the record you are updating has an incorrect field value. A response with this status is often accompanied by a list of errors in the response body.
401 Unauthorized The credentials specified via HTTP Basic Authentication were invalid.
404 Not Found The resource you have referenced could not be found.
405 Method Not Allowed The method you are using to access (GET, POST, PUT, etc.), is not allowed for the requested resource.
406 Not Acceptable You have referenced the media type requesting a format that is unsupported.
415 Unsupported Media Type You have referenced the media type requesting a format that is unsupported. Most resources are available as XML only, though a few have alternate types as described in this API documentation.
500 Internal Server Error There has been an error from which Unfuddle could not recover. There is a high likelihood that an internal server error represents a bug on the part of Unfuddle. Unfuddle Support automatically receives notifications of these errors for further investigation.

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

Certain requests to the STACK 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

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>