= Heroku REST API
 
Typically the command-line program is used for manually manipulating Heroku
apps; or from a Ruby script (like a Rakefile), one uses the Heroku::Client
class.  This document describes the underlying REST API used by both.
 
== Authentication
 
Use HTTP basic auth to provide the Heroku username (email) and password with
each request.
 
== Content Types
 
Actions that take additional input besides the verb and URL fall into two
categories: XML/formencoded, or plaintext.  Actions that take multiple input
parameters (such as updating the app settings) accept either an XML input body,
or form variables as an input body in x-www-form-urlencoded format.  Actions
that take a block of code or text data (such as uploading an ssh key) expect a
plaintext input body.
 
Most actions return XML, except for a few that return plaintext (such as the
output of rake).
 
== Resources & Actions
 
  GET http://heroku.com/apps
 
Returns XML listing of apps belonging to the user.
 
  POST http://heroku.com/apps
 
Create a new app with an untitled name.  Returns XML of app settings, including
the generated name.
 
  POST http://heroku.com/apps
    app[name]=:appname
 
Create a new app with the provided name.  Returns XML of app settings.
 
  GET http://heroku.com/apps/:appname
 
Returns XML of the app settings (the same data returned after creation).
 
  PUT http://heroku.com/apps/:appname
 
Update app settings, with input structure matching the output of the GET above.
 
  GET http://heroku.com/apps/:appname/collaborators
 
Returns XML list of collaborators (email addresses) on the app
 
  POST http://heroku.com/apps/:appname/collaborators
    collaborator[email]=:email
 
Add a new collaborator to the app.
 
  DELETE http://heroku.com/apps/:appname/collaborators/:email
 
Delete a collaborator from the app.  Don't forget to urlencode the email, since
@ signs are not valid in URLs.
 
  POST http://heroku.com/apps/:appname/rake
 
Execute a rake command on the app.  The input body should be plaintext
containing the command.  Returns a plaintext output body with the rake output.
 
  DELETE http://heroku.com/apps/:appname
 
Permanently destroy the app.
 
  POST http://heroku.com/user/keys
 
Upload an ssh public key.  The input body is plaintext containing the key
contents, usually around 200 bytes for an RSA key and 600 bytes for a DSA key.
Make sure you are uploading the public portion of the key (e.g.,
~/.ssh/id_rsa.pub) and not the private portion (e.g. ~/.ssh/id_rsa).
 
  GET http://heroku.com/user/keys
 
Returns XML of user's current keys.
 
  DELETE http://heroku.com/user/keys/:keyname
 
Delete one key by its name.  The name is the portion at the end of the key,
e.g. a key like "ssh-rsa AAAAB3NzaC1yc2EAlmn+I0= joe@joe-smiths-computer.local"
has a keyname of joe@joe-smiths-computer.local.  Remember to urlencode the
keyname, since @ is not a valid URL character.
 
== Example
 
Although one would normally use Heroku::Client from a Ruby program, here's some
sample code for reference.  It creates an app named foobaz by posting to /apps.
 
Using Net::HTTP:
 
  require 'net/http'
 
  Net::HTTP.start('heroku.com') do |http|
    request = Net::HTTP.Post.new('/apps')
    request.basic_auth 'me@example.com', 'mypass'
    res = http.request(request, 'app[name]=foobaz')
    puts res.body
  end
 
Using the RestClient gem:
 
  require 'rubygems'
  require 'rest_client'
 
  apps = RestClient::Resource.new('http://heroku.com/apps', 'me@example.com', 'mypass')
  apps.post :app => { :name => 'foobaz' }