Permalink
Fetching contributors…
Cannot retrieve contributors at this time
113 lines (70 sloc) 3.42 KB
= 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' }