Unfuddle STACK API

Usage Scenarios

Reference

Accounts

Introduction

Each Unfuddle subdomain has exactly one Account resource associated with it.

Account

The Unfuddle Account. Contains very basic, high level information about the Account.

URL:
/api/v1/account[GET, PUT]
Response Formats:
XML, JSON, ICS
Request/Response Body:
See Account Data Model
Example:
curl -i -u username:password -X PUT \\
  -H 'Accept: application/xml' \\
  -H 'Content-Type: application/xml' \\
  -d '<account><text-markup>>textile</text-markup></account>' \\
  https://mysubdomain.unfuddle.com/api/v1/account.xml

Account Activity

The activity for all Projects to which the requesting person has access. Query parameters can be passed via the query string parameters or in the request body. If no dates are given, activity for the last two weeks is returned.

URL:
/api/v1/account/activity[GET]
Response Formats:
XML, JSON, RSS
Parameters (via query string or request body):
<request>
  <!-- specifies the inclusive start date of the query -->
  <start-date>2007/1/1</start-date>
  <!-- specifies the inclusive end date of the query -->
  <end-date>2007/12/31</end-date>
  <!-- specifies the maximum number of results to return -->
  <limit>50</limit>
</request>
Response Body:
<events>
  <event>
    <project-id type="integer"> </project-id>
    <created-at type="datetime"> </created-at>
    <record-type> [Message, Milestone, Ticket, TimeEntry, Changeset, Comment] </record-type>
    <record-id type="integer"> </record-id>
    <event> [accept, close, commit, create, delete, reopen, resolve, unaccept, status_update] </event>
    <description> </description>
    <person-id type="integer"> </person-id>
    <summary> </summary>

    <!--
      if a record exists, then it will be included here.
      note that only ONE of these will exist, corresponding to record-type
      see data model documentation for format.
    -->
    <record>
      <message> ... </message>
      <milestone> ... </milestone>
      <ticket> ... </ticket>
      <time-entry> ... </time-entry>
      <changeset> ... </changeset>
      <comment> ... </comment>
    </event>
</events>
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  -H 'Content-Type: application/xml' \\
  -d '<request><start-date>>5/5/2007</start-date><end-date>>5/12/2007</end-date></request>' \\
  https://mysubdomain.unfuddle.com/api/v1/account/activity.xml

Account Search

Searches through all projects to which the requester person has access for instances of the given query string. Query parameters can be passed via the query string parameter or in the request body.

URL:
/api/v1/account/search[GET]
Response Formats:
XML, JSON
Parameters (via query string or request body):
<request>
  <!-- REQUIRED: specifies the text of the query -->
  <query>dashboard widget</query>
  <!-- zero-based index specifies where to start in the results (for pagination) -->
  <start-index>20</start-index>
  <!-- zero-based index specifies where to end in the results (for pagination) -->
  <end-index>39</end-index>
  <!-- specifies the number of results that will be returned for each filter, for each project in the account -->
  <limit>5</limit>
  <!-- comma separated string of object types by which to filter -->
  <filter>changesets,comments,messages,milestones,notebooks,tickets</filter>
</request>
Response Body:
<results>
  <result>
    <type> [Changeset, Comment, Message, Milestone, Ticket] </type>
    <location> </location>
    <title> </title>
    <description> </description>
    <updated-at type="datetime"> </updated-at>

    <!-- does not exist for results of type 'Milestone' or 'Ticket' -->
    <author-id> </author-id>

    <!-- exists only for results of type 'Milestone' -->
    <archived> </archived>
    <completed> </completed>
    <due-on> </due-on>

    <!-- exists only for results of type 'Ticket' -->
    <status> </status>

  </result>
  ...
</results>
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  -H 'Content-Type: application/xml' \\
  -d '<request><query>>john support dashboard</query></request>' \\
  https://mysubdomain.unfuddle.com/api/v1/account/search.xml

Reset Access Keys

Resets access keys for the account and for all users within the Account, thus invalidating all RSS and iCal feeds out in the wild.

URL:
/api/v1/account/reset_access_keys[PUT]
Example:
curl -i -u username:password -X PUT \\
  -H 'Accept: application/xml' \\
  https://mysubdomain.unfuddle.com/api/v1/account/reset_access_keys

Initializer

A convenience resource that provides many of the top level items in an account in a single call. When developing applications against the STACK API, using this resource can save literally hundreds of calls when building an initial client-side cache.

URL:
/api/v1/initializer[GET]
Response Formats:
XML, JSON
Response Body:
<initializer>

  <account>...</account>

  <people>
    <person>...</person>
    <person>...</person>
  </people>

  <projects>
    <project>...</project>
    <project>...</project>
  </projects>

  <repositories>
    <repository>...</repository>
    <repository>...</repository>
  </repositories>

  <!-- all involvements for all projects -->
  <involvements>
    <involvement>...</involvement>
    <involvement>...</involvement>
  </involvements>

  <!-- all severities for all projects -->
  <severities>
    <severity>...</severity>
    <severity>...</severity>
  </severities>

  <!-- all components for all projects -->
  <components>
    <component>...</component>
    <component>...</component>
  </components>

  <!-- all versions for all projects -->
  <versions>
    <version>...</version>
    <version>...</version>
  </versions>

  <!-- all milestones for all projects -->
  <milestones>
    <milestone>...</milestone>
    <milestone>...</milestone>
  </milestones>

  <!-- all custom field values for all projects -->
  <custom-field-values>
    <custom-field-value>...</custom-field-value>
    <custom-field-value>...</custom-field-value>
  </custom-field-values>

  <!-- all categories for all projects -->
  <categories>
    <category>...</category>
    <category>...</category>
  </categories>

</initializer>
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  https://mysubdomain.unfuddle.com/api/v1/initializer.xml

Formatter

A convenience resource that can be used to format text fields that support Markups such as Markdown, Textile or Unfuddle markup conventions (i.e message body, ticket description). This can be used when you want to avoid getting all messages or all tickets with formatted parameter set to true, but format the markup fields just for the resources displayed on the current page.

URL:
/api/v1/account/formatter[POST]
Response Formats:
XML, JSON
Parameters (via query string or request body):
<request>
  <!-- REQUIRED: specifies the text of the query -->
  <text>some text to be formatted</text>
  <!-- the markup style that will be used to format the text.
  If not specified the default format from the account settings will be used  -->
  <markup>Markdawn</markup>
</request>
Response Body:
<formatted_text>
  <div class="markdown_formatted">Formatted text.</div>
</formatted_text>
Example:
curl -i -u username:password -X POST \\
  -H 'Accept: application/xml' \\
  -H 'Content-Type: application/xml' \\
  -d '<request><text>Some text to format.</text></request>' \\
  https://mysubdomain.unfuddle.com/api/v1/account/formatter.xml