Unfuddle STACK API

Usage Scenarios

Reference

Repositories

Introduction

Each Unfuddle Account can have any number of Repositories associated with it. These Repositories can then be associated with any number of Unfuddle Projects.

Each Repository has many Changesets associated with it. By default, Unfuddle will create a Changeset object whenever a commit happens on a repository. These Changesets are essentially a mirror of commit related information stored in the Unfuddle databases to speed up web-based reporting and email notification as introspecting the repository itself can often be a very expensive operation.

This opens up some interesting opportunities, especially to those customers wishing to host an external repository for their Project. If you are hosting an external repository for your Project, but still wish to receive notification of updates to the repository via Unfuddle activity feeds and emails, you may choose to manually create Changesets for the Repository (i.e. via Subversion "post-commit" or Git "post-receive" hook scripts).

If you wish to assume the responsibility of managing Changesets for your Repository, because your repository is hosted elsewhere or for any other reason, please note that you must first indicate to Unfuddle that it is no longer responsible for automatically managing Changesets. To do this, please be sure to check "Changesets Managed Manually" from the Repository edit screen.

Repositories

The collection represents all Repositories within an Account.

URL:
/api/v1/repositories[GET, POST]
/api/v1/repositories/{id}[GET, PUT, DELETE]
Response Formats:
XML, JSON, RSS
Request/Response Body:
See Repository Data Model
Example:
curl -i -u username:password -X POST \\
  -H 'Accept: application/xml' \\
  -H 'Content-Type: application/xml' \\
  -d "<repository><abbreviation>mynewrepo</abbreviation><title>My New Repo</title><system>svn</system><projects><project id='30226'/></projects></repository>" \\
  'https://mysubdomain.unfuddle.com/api/v1/repositories'

Changesets

The collection represents all Changesets within a Repository.

URL:
/api/v1/repositories/{id}/changesets[GET, POST]
/api/v1/repositories/{id}/changesets/{id}[GET, PUT, DELETE]
/api/v1/repositories/{id}/commit/{revision}[GET, PUT, DELETE]
/api/v1/projects/{id}/changesets [DEPRECATED][GET, POST]
/api/v1/projects/{id}/changesets/{id} [DEPRECATED][GET, PUT, DELETE]
Response Formats:
XML, JSON, RSS
Parameters (via query string or request body):
<request>
  <!-- specifies whether or not to process message actions on (POST only) -->
  <process-message-actions> [true, false] </process-message-actions>
</request>
Request/Response Body:
See changeset Data Model
Example:
curl -i -u username:password -X POST \\
  -H 'Accept: application/xml' \\
  -H 'Content-Type: application/xml' \\
  -d '<changeset><revision>512</revision><message>Unfuddled the Widgetizer</message></changeset>' \\
  'https://mysubdomain.unfuddle.com/api/v1/projects/3455/changesets?process_message_actions=true'

Latest Changeset

Returns the most recently committed Changeset within a Repository.

URL:
/api/v1/repositories/{id}/changesets/latest[GET, POST]
/api/v1/projects/{id}/changesets/latest [DEPRECATED][GET, POST]
Response Formats:
XML, JSON
Response Body:
See changeset Data Model
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  https://mysubdomain.unfuddle.com/api/v1/projects/3455/changesets/latest.xml

Process Message Actions

Unfuddle is capable of processing the commit message for any Changeset and using it to modify the status of tickets (i.e. "Closed #432"). Performing an HTML PUT to this resource will process any actions that are present in the commit message. Note that the actions will only be process if "Powerful Commit Messages" are active for the given repository.

URL:
/api/v1/repositories/{id}/changesets/{id}/process_message_actions[PUT]
/api/v1/projects/{id}/changesets/{id}/process_message_actions [DEPRECATED][PUT]
Response Formats:
XML, JSON
Response Body:
See changeset Data Model
Example:
curl -i -u username:password -X PUT \\
  -H 'Accept: application/xml' \\
  https://mysubdomain.unfuddle.com/api/v1/projects/3455/changesets/98673/process_message_actions.xml

Commit

Returns a representation of a Commit in a Repository. This includes commit information, file diffs and comments on the commit.

URL:
/api/v1/repositories/{id}/commit[GET]
Response Formats:
XML, JSON
Parameters (via query string or request body):
<request>
    <!-- specifies the commit; if missing, HEAD is assumed -->
    <commit> </commit>
  </request>
Response Body:
<commit>
    <author> </author>
    <author-date type="datetime"> </author-date>
    <author-email> </author-email>
    <branch> </branch>
    <commit> </commit>
    <committer> </committer>
    <committer-email> </committer-email>
    <committer-date type="datetime"> </committer-date>
    <!-- Contains Unidiff formatted differentials for each file modified by the specified commit -->
    <diffs>
      <diff filename=""> </diff>
      ...
    </diffs>
    <files>
      <file>
        <type> </type>
        <action> </action>
        <content> </content>
        <name> </name>
      </file>
      ...
    </files>
    <message> </message>
    <parents>
      <parent> </parent>
      ...
    </parents>
    <tag> </tag>
    <tree> </tree>
  </commit>
Example:
curl -i -u username:password -X GET \\
    -H 'Accept: application/xml' \\
    'https://mysubdomain.unfuddle.com/api/v1/repositories/18/commit.xml?commit=bbee5085e4733dcfa7275c594d01d3b738575546'

Diff

Returns a Unidiff file to reflect changes in the specified commit.

URL:
/api/v1/repositories/{id}/diff[GET]
Response Formats:
DIFF
Parameters (via query string or request body):
<request>
    <!-- specifies the commit; if missing, HEAD is assumed -->
    <commit> </commit>
  </request>
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: text/x-diff' \\
  https://mysubdomain.unfuddle.com/api/v1/repositories/18/diff?commit=ddbace4cd9733b4fa56077ed241e6682c0110d05

Download

Returns the requested file at the specified revision.

URL:
/api/v1/repositories/{id}/download[GET]
Response Formats:
FILE
Parameters (via query string or request body):
<request>
    <!-- specifies the commit; if missing, HEAD is assumed -->
    <commit> </commit>
    <!-- specifies the path to the file; if missing, 500 is returned. -->
    <path> </path>
  </request>
Example:
curl -i -u username:password -X GET \\
  https://mysubdomain.unfuddle.com/api/v1/repositories/18/download?path=/README.txt&commit=ddbace4cd9733b4fa56077ed241e6682c0110d05

File

Returns a representation of the requested file.

URL:
/api/v1/repositories/{id}/file[GET]
Response Formats:
XML, JSON
Parameters (via query string or request body):
<request>
    <!-- specifies the commit; if missing, HEAD is assumed -->
    <commit> </commit>
    <!-- specifies the path to the file -->
    <path> </path>
    <!-- includes the changeset object pertaining to each line in the file -->
    <blame> [true, false] </blame>
  </request>
Response Body:
<file>
    <commit> </commit>
    <content-type> </content-type>
    <!-- Size value in Bytes -->
    <size> </size>
    <name> </name>
    <committer-date type="datetime"> </committer-date>
    <!-- Contains Unidiff formatted differentials for each file modified by the specified commit -->
    <lines>
      <line>
        <content> </content>
        <!-- Only if blame=true -->
        <changeset> </changeset>
        <number> </number>
      </line>
      ...
    </lines>
  </file>
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  https://mysubdomain.unfuddle.com/api/v1/repositories/18/file?path=/README.txt&commit=ddbace4cd9733b4fa56077ed241e6682c0110d05&blame=true

History

Returns the history of a specific file.

URL:
/api/v1/repositories/{id}/history[GET]
Response Formats:
XML, JSON
Parameters (via query string or request body):
<request>
    <!-- specifies the commit; if missing, HEAD is assumed -->
    <commit> </commit>
    <!-- specifies the path whose history is requested -->
    <path> </path>
    <!-- for pagination purposes; if missing, 1 is assumed -->
    <page> </page>
    <!-- for pagination purposes; number of history items to be displayed on a page; if missing, 10 is assumed -->
    <count> </count>
  </request>
Response Body:
<history>
    <commit>
      <author> </author>
      <author-date type="datetime"> </author-date>
      <author-email> </author-email>
      <branch> </branch>
      <!-- The Changeset object created for this commit -->
      <changeset></changeset>
      <commit> </commit>
      <committer> </committer>
      <committer-email> </committer-email>
      <committer-date type="datetime"> </committer-date>
      <!-- Contains Unidiff formatted differentials for each file modified by the specified commit -->
      <message> </message>
      <parents>
        <parent> </parent>
        ...
      </parents>
      <!-- [dir, file] -->
      <scope></scope>
      <tag> </tag>
      <tree> </tree>
      <!-- The total count of history items -->
      <total-count> </total-count>
    </commit>
  </history>
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  https://mysubdomain.unfuddle.com/api/v1/repositories/18/history.xml?path=/README.txt&commit=ddbace4cd9733b4fa56077ed241e6682c0110d05

Tree

Returns a representation of the requested directory.

URL:
/api/v1/repositories/{id}/tree[GET]
Response Formats:
XML, JSON
Parameters (via query string or request body):
<request>
    <!-- specifies the commit; if missing, HEAD is assumed -->
    <commit> </commit>
    <!-- specifies the path to the file; if missing, / is assumed -->
    <path> </path>
  </request>
Response Body:
<tree>
    <commit> </commit>
    <content-type> </content-type>
    <!-- Size value in Bytes -->
    <size> </size>
    <name> </name>
    <committer-date type="datetime"> </committer-date>
    <nodes>
      <node>
        <type> </type>
        <size> </size>
        <name> </name>
      </node>
      ...
    </nodes>
  </tree>
Example:
curl -i -u username:password -X GET \\
  -H 'Accept: application/xml' \\
  https://mysubdomain.unfuddle.com/api/v1/repositories/18/tree?commit=ddbace4cd9733b4fa56077ed241e6682c0110d05