Unfuddle API: Code Examples

Curl top

The ubiquitous Curl HTTP client is probably the quickest way to get started with the Unfuddle API. It can easily be used in scripts (such as post-commit hooks) to interact with you Unfuddle Account.

HTTP GET

The following example gets the XML representation of the project with an id ZZZZ via an HTTP GET.

curl -i -u username:password -X GET \
  -H 'Accept: application/xml' \
  'http://mysubdomain.unfuddle.com/api/v1/projects/ZZZZ.xml'

HTTP POST

The following example creates a new message in the project with an id ZZZZ via an HTTP POST.

curl -i -u username:password -X POST \
  -H 'Accept: application/xml' \
  -H 'Content-type: application/xml' \
  -d "<message><title>My New Message</title><body>Body text goes here...</body><body-format>markdown</body-format><categories><category id='545'/></categories></message>" \
  'http://mysubdomain.unfuddle.com/api/v1/projects/ZZZZ/messages'

Ruby NET::HTTP top

Ruby comes out of the box with a fairly robust HTTP client library. The following example code will perform two actions in sequence. First it will get an XML listing of projects within an account via an HTTP GET, then it perform an HTTP POST to create a message in a project with an id of ZZZZ.

require 'net/https'

UNFUDDLE_SETTINGS = {
  :subdomain  => 'mysubdomain',
  :username   => 'username',
  :password   => 'password',
  :ssl        => true
}

http = Net::HTTP.new("#{UNFUDDLE_SETTINGS[:subdomain]}.unfuddle.com", UNFUDDLE_SETTINGS[:ssl] ? 443 : 80)

# if using ssl, then set it up
if UNFUDDLE_SETTINGS[:ssl]
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE
end

# perform an HTTP GET
begin
  request = Net::HTTP::Get.new('/api/v1/projects.xml')
  request.basic_auth UNFUDDLE_SETTINGS[:username], UNFUDDLE_SETTINGS[:password]

  response = http.request(request)
  if response.code == "200"
    puts response.body
  else
    # hmmm...we must have done something wrong
    puts "HTTP Status Code: #{response.code}."
  end
rescue => e
  # do something smart
end

# perform an HTTP POST
# if testing, be sure to use a valid project id below
begin
  request = Net::HTTP::Post.new('/api/v1/projects/ZZZZ/messages.xml', {'Content-type' => 'application/xml'})
  request.basic_auth UNFUDDLE_SETTINGS[:username], UNFUDDLE_SETTINGS[:password]
  request.body = "<message><title>A New Message from the API</title><body>Pretty cool, huh?</body></message>"

  response = http.request(request)
  if response.code == "201"
    puts "Message Created: #{response['Location']}"
  else
    # hmmm...we must have done something wrong
    puts "HTTP Status Code: #{response.code}."
  end
rescue => e
  # do something smart
end

PHP top

HTTP GET

The following example will get a listing of projects within the account in XML format via an HTTP GET and output some basic information about them. Thanks to Tom Power for providing the example.

// Edit your values here to match your account settings.
$config_method = 'GET';
$config_userpass = 'username:password';
$config_headers[] = 'Accept: application/xml';
$config_address = 'http://subdomain.unfuddle.com/api/v1/';
$config_datasource = 'projects.xml';

// Here we set up CURL to grab the data from Unfuddle
$chandle = curl_init();
curl_setopt($chandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chandle, CURLOPT_URL, $config_address . $config_datasource);
curl_setopt($chandle, CURLOPT_HTTPHEADER, $config_headers);
curl_setopt($chandle, CURLOPT_USERPWD, $config_userpass);
curl_setopt($chandle, CURLOPT_CUSTOMREQUEST, $config_method);
$output = curl_exec($chandle);
curl_close($chandle);

// XML in PHP is simple to use with SimpleXML, go figure!
$xml = new SimpleXMLElement($output);

foreach ($xml->project as $project) {
  echo '(ID: ' . $project->{'id'} . ') - ' . $project->{'title'};
  echo '-------------------------------------------------------';
  echo $project->{'description'};
  echo '-------------------------------------------------------';
  echo 'Repos: ' . $project->{'repo-name'};
  echo 'Created: ' . $project->{'created-at'};
  echo 'Last mod: ' . $project->{'updated-at'};
  echo '-------------------------------------------------------';
}

C# (.NET) top

HTTP GET

The following example will get a listing of projects within the account in XML format via an HTTP GET. Thanks to Lance Sun for providing the example.

string url = "https://mysubdomain.unfuddle.com/api/v1/projects.xml";
string username = "username";
string password = "password";
string credentials = String.Format( "{0}:{1}", username, password );
string basicAuth = Convert.ToBase64String( Encoding.ASCII.GetBytes( credentials ) );
WebRequest request = WebRequest.Create( url );
request.Headers.Add( "Authorization", "Basic " + basicAuth );
WebResponse response = request.GetResponse();
StreamReader reader = new StreamReader( response.GetResponseStream() );
Console.WriteLine( reader.ReadToEnd() );

JavaScript top

With the inclusion JSON to the Unfuddle API, consuming it from JavaScript is a breeze. We strongly suggest using a JavaScript library such as Prototype.

Note that you must manually add the Authorization header to the request with your credentials base64 encoded. This can be easily done with any JavaScript base64 encoding/decoding library available out there.

HTTP GET

The following example will get a listing of projects within the account in JSON format via an HTTP GET. The response body is then eval'ed and stored in the variable projects_array.

var projects_array = [];
new Ajax.Request("https://https://mysubdomain.unfuddle.com/api/v1/projects.json", {
  method: 'get',
  requestHeaders: [ "Authorization", "Basic " + base64_encode('username:password'), "Authorization", "Accept", "application/json" ],
  onSuccess: function(transport) {
    if(transport.status == 200) {
      // now we can just eval the responseText and get a JavaScript object
      project_array = transport.responseText.evalJSON();
      alert('Project Total: ' + project_array.length);
    }
  },
  onFailure: function(transport) {
    alert('Something went wrong!');
  }
});

HTTP POST

The following example creates a new message in the project with an id ZZZZ via an HTTP POST. Note that the post data must be in XML format.

new Ajax.Request("https://https://mysubdomain.unfuddle.com/api/v1/projects/ZZZZ/messages.json", {
  method: 'post',
  postBody: "<message><title>A New Message from the API</title><body>Pretty cool, huh?</body></message>",
  requestHeaders: [ "Authorization", "Basic " + base64_encode('username:password'), "Accept", "application/json", "Content-type" , "application/xml"],
  onSuccess: function(transport) {
    if(transport.status == 201)
      alert("Message Created: " + transport.getHeader('Location'));
  },
  onFailure: function(transport) {
    // Identifiable errors are returned as a JSON array of strings
    alert("The following errors occurred: \n\n" + (transport.responseText.evalJSON() || []).join("\n"));
  }
});