com.heroku.api
Class HerokuAPI

java.lang.Object
  com.heroku.api.HerokuAPI

public class HerokuAPI
extends Object

A convenience class for making HTTP requests to the Heroku API for a given user. An underlying Connection is created for each instance of HerokuAPI. To make HTTP requests to the Heroku API in multi-user or systems that have resource constraints (e.g. a pool of Connection objects are required), Connection should be used directly.

Example usage:

HerokuAPI heroku = new HerokuAPI("apiKey");
     App app = heroku.createApp();
     heroku.scaleProcess(app.getName(), "web", 1)
 
 

RuntimeException will be thrown for any request failures.

Field Summary

protected String	apiKey
protected Connection	connection

Constructor Summary

HerokuAPI(Connection connection, String apiKey)

HerokuAPI(String apiKey)
Constructs a HerokuAPI with a Connection based on the first ConnectionProvider found on the classpath.

Method Summary

AddonChange	addAddon(String appName, String addonName) Add an addon to the app.
void	addCollaborator(String appName, String collaborator) Add a collaborator to an app.
void	addConfig(String appName, Map<String,String> config) Add environment variables to an app.
void	addKey(String sshKey) Add an ssh key to the current user's account.
boolean	appExists(String name) Checks if an app with the given name exists on Heroku.
App	cloneApp(String templateAppName) Clone an existing app that has previously been designated as a template into the authenticated user's account with a randomly generated name.
App	cloneApp(String templateAppName, App targetApp) Clone an existing app that has previously been designated as a template into the authenticated user's account with details specified in the target app.
App	createApp() Create a new app on the Heroku.Stack.Cedar stack.
App	createApp(App app) Create a new app using App to specify parameters.
void	destroyApp(String appName) Delete an app.
App	getApp(String name) Get information about a specific app.
Connection	getConnection()
LogStreamResponse	getLogs(Log.LogRequestBuilder logRequest) Get logs for an app by specifying additional parameters.
LogStreamResponse	getLogs(String appName) Get logs for an app.
Release	getReleaseInfo(String appName, String releaseName) Information about a specific release.
User	getUserInfo() Information for the current user.
boolean	isAppNameAvailable(String name) Checks if the given app name is available on Heroku.
boolean	isMaintenanceModeEnabled(String appName) Checks if maintenance mode is enabled for the given app
List<Addon>	listAllAddons() Get a list of all addons available.
List<Addon>	listAppAddons(String appName) List the addons already added to an app.
List<App>	listApps() List all apps for the current user's account.
List<StackInfo>	listAppStacks(String appName) Gets a list of stacks available.
List<Collaborator>	listCollaborators(String appName) Get a list of collaborators that are allowed access to an app.
Map<String,String>	listConfig(String appName) List all the environment variables for an app.
List<Key>	listKeys() Get a list of keys associated with the current user's account.
List<Proc>	listProcesses(String appName) List of processes running for an app.
List<Release>	listReleases(String appName) List of releases for an app.
String	migrateStack(String appName, Heroku.Stack migrateTo) Migrates an app from its current stack to the specified stack.
static String	obtainApiKey(String username, String password) Logs into the Heroku API and retrieves an API key for a given username and password using HTTP Basic Authentication.
AddonChange	removeAddon(String appName, String addonName) Remove an addon from an app.
void	removeCollaborator(String appName, String collaborator) Remove a collaborator from an app.
Map<String,String>	removeConfig(String appName, String configVarName) Remove an environment variable from an app.
void	removeKey(String sshKey) Delete an ssh key from the current user's account.
String	renameApp(String appName, String newName) Rename an existing app.
void	restart(String appName) Restart an app.
void	restartProcessByName(String appName, String procName) Restart a named process.
void	restartProcessByType(String appName, String type) Restart a process for an app.
String	rollback(String appName, String releaseName) Rollback an app to a specific release.
void	run(String appName, String command) Run a one-off process on a Heroku dyno.
RunResponse	runAttached(String appName, String command) Run a one-off process on a Heroku dyno in an attached state.
void	scaleProcess(String appName, String processType, int quantity) Change the number of processes running for a given process type.
void	setMaintenanceMode(String appName, boolean enable) Sets maintenance mode for the given app
void	transferApp(String appName, String to) Transfer the ownership of an application to another user.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

connection

protected final Connection connection

apiKey

protected final String apiKey

Constructor Detail

HerokuAPI

public HerokuAPI(String apiKey)

Constructs a HerokuAPI with a Connection based on the first ConnectionProvider found on the classpath.

Parameters:

apiKey - User's API key found at https://api.heroku.com/account

HerokuAPI

public HerokuAPI(Connection connection,
                 String apiKey)

Parameters:

connection -

apiKey - User's API key found at https://api.heroku.com/account

Method Detail

obtainApiKey

public static String obtainApiKey(String username,
                                  String password)

Logs into the Heroku API and retrieves an API key for a given username and password using HTTP Basic Authentication.

Parameters:

username - Heroku username.

password - Heroku password.

Returns:

An API key that can be used for subsequent API calls.

getConnection

public Connection getConnection()

getUserInfo

public User getUserInfo()

Information for the current user.

Returns:

addKey

public void addKey(String sshKey)

Add an ssh key to the current user's account.

Parameters:

sshKey - Public key value. e.g. ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCz29znMi/UJX/nvkRSO5FFugKhU9DkkI53E0vXUnP8zeLFxMgyUqmXryPVjWtGzz2LRWqjm14SbqHAmM44pGHVfBIp6wCKBWSUYGv/FxOulwYgtWzz4moxWLZrFyWWgJAnehcVUifHNgzKwT2ovWm2ns52681Z8yFK3K8/uLStDjLIaPePEOaxaTvgIxZNsfyEoXoHcyTPwdR1GtQuDTuDYqYmjmPCoKybYnXrTQ1QFuQxDneBkswQYSl0H2aLf3uBK4F01hr+azXQuSe39eSV4I/TqzmNJlanpILT9Jz3/J1i4r6brpF3AxLnFnb9ufIbzQAIa/VZIulfrZkcBsUl [email protected]

removeKey

public void removeKey(String sshKey)

Delete an ssh key from the current user's account.

Parameters:

sshKey - The comment in the public key. See listKeys() to get a list of keys that can be removed.

listKeys

public List<Key> listKeys()

Get a list of keys associated with the current user's account.

Returns:

listApps

public List<App> listApps()

List all apps for the current user's account.

Returns:

getApp

public App getApp(String name)

Get information about a specific app.

Parameters:

name - The name of the app. See listApps() to get a list of apps and their names.

Returns:

appExists

public boolean appExists(String name)

Checks if an app with the given name exists on Heroku. A true response does not necessarily indicate the user has access to the app. Use getApp(String) to check user access.

Parameters:

name - name of the app

Returns:

true if an app exists with the specified name

isAppNameAvailable

public boolean isAppNameAvailable(String name)

Checks if the given app name is available on Heroku.

Parameters:

name - name of the app

Returns:

true if the app name is available

createApp

public App createApp()

Create a new app on the Heroku.Stack.Cedar stack. For more information about the Cedar stack, please see the Dev Center.

Returns:

createApp

public App createApp(App app)

Create a new app using App to specify parameters. App has convenience methods for specifying parameters to send as part of the request. Typically, these will be the name of the app and the requested stack. e.g.

heroku.createApp(new App().on(Heroku.Stack.Cedar).named("new-app")

Parameters:

app - See App

Returns:

cloneApp

public App cloneApp(String templateAppName)

Clone an existing app that has previously been designated as a template into the authenticated user's account with a randomly generated name. App cloning is only supported on the Heroku.Stack.Cedar stack.

Parameters:

templateAppName - Name of the template app to clone.

Returns:

details about the cloned app

cloneApp

public App cloneApp(String templateAppName,
                    App targetApp)

Clone an existing app that has previously been designated as a template into the authenticated user's account with details specified in the target app. Currently, only specifying the name of the target app is supported. App cloning is only supported on the Heroku.Stack.Cedar stack.

Parameters:

templateAppName - Name of the template app to clone.

targetApp - Details about the target app.

Returns:

details about the cloned targetApp

renameApp

public String renameApp(String appName,
                        String newName)

Rename an existing app.

Parameters:

appName - Existing app name. See listApps() for names that can be used.

newName - New name to give the existing app.

Returns:

destroyApp

public void destroyApp(String appName)

Delete an app.

Parameters:

appName -

addAddon

public AddonChange addAddon(String appName,
                            String addonName)

Add an addon to the app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

addonName - Addon name. See listAllAddons() to get a list of addons that can be used.

Returns:

listAllAddons

public List<Addon> listAllAddons()

Get a list of all addons available. Refer to http://addons.heroku.com for more information about addons.

Returns:

listAppAddons

public List<Addon> listAppAddons(String appName)

List the addons already added to an app.

Parameters:

appName -

Returns:

removeAddon

public AddonChange removeAddon(String appName,
                               String addonName)

Remove an addon from an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

addonName - Addon name. See listAppAddons(java.lang.String) for a list of addons that can be used.

Returns:

scaleProcess

public void scaleProcess(String appName,
                         String processType,
                         int quantity)

Change the number of processes running for a given process type.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

processType - Process name. See listProcesses(java.lang.String) for a list of processes that can be used.

quantity - The number to scale the process to.

listProcesses

public List<Proc> listProcesses(String appName)

List of processes running for an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

Returns:

listReleases

public List<Release> listReleases(String appName)

List of releases for an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

Returns:

rollback

public String rollback(String appName,
                       String releaseName)

Rollback an app to a specific release.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

releaseName - Release name. See listReleases(java.lang.String) for a list of the app's releases.

Returns:

getReleaseInfo

public Release getReleaseInfo(String appName,
                              String releaseName)

Information about a specific release.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

releaseName - Release name. See listReleases(java.lang.String) for a list of the app's releases.

Returns:

listCollaborators

public List<Collaborator> listCollaborators(String appName)

Get a list of collaborators that are allowed access to an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

Returns:

addCollaborator

public void addCollaborator(String appName,
                            String collaborator)

Add a collaborator to an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

collaborator - Username of the collaborator to add. This is usually in the form of "[email protected]".

removeCollaborator

public void removeCollaborator(String appName,
                               String collaborator)

Remove a collaborator from an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

collaborator - See listCollaborators(java.lang.String) for collaborators that can be removed from the app.

addConfig

public void addConfig(String appName,
                      Map<String,String> config)

Add environment variables to an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

config - Key/Value pairs of environment variables.

listConfig

public Map<String,String> listConfig(String appName)

List all the environment variables for an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

Returns:

removeConfig

public Map<String,String> removeConfig(String appName,
                                       String configVarName)

Remove an environment variable from an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

configVarName - Name of the environment variable. See listConfig(java.lang.String) for variables that can be removed

Returns:

transferApp

public void transferApp(String appName,
                        String to)

Transfer the ownership of an application to another user.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

to - Username of the person to transfer the app to. This is usually in the form of "[email protected]".

getLogs

public LogStreamResponse getLogs(String appName)

Get logs for an app.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

Returns:

getLogs

public LogStreamResponse getLogs(Log.LogRequestBuilder logRequest)

Get logs for an app by specifying additional parameters.

Parameters:

logRequest - See LogRequestBuilder

Returns:

run

public void run(String appName,
                String command)

Run a one-off process on a Heroku dyno.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

command - Bash command to run inside a dyno. See One-off processes.

runAttached

public RunResponse runAttached(String appName,
                               String command)

Run a one-off process on a Heroku dyno in an attached state. Running in an attached state allows for interactive input. Refer to RunResponse.attach() for more information on running an attached process.

Parameters:

appName - App name. See listApps() for a list of apps that can be used.

command - Bash command to run inside a dyno. See One-off processes.

Returns:

restart

public void restart(String appName)

Restart an app.

Parameters:

appName - See listApps() for a list of apps that can be used.

restartProcessByType

public void restartProcessByType(String appName,
                                 String type)

Restart a process for an app.

Parameters:

appName - See listApps() for a list of apps that can be used.

type - The type of process to restart. e.g. web, worker, etc...

restartProcessByName

public void restartProcessByName(String appName,
                                 String procName)

Restart a named process.

Parameters:

appName - See listApps() for a list of apps that can be used.

procName - Name of process to restart.

migrateStack

public String migrateStack(String appName,
                           Heroku.Stack migrateTo)

Migrates an app from its current stack to the specified stack. Stacks must be compatible with one another. e.g. an app can be migrated from com.heroku.api.Heroku.Stack.Bamboo187 to com.heroku.api.Heroku.Stack.Bamboo192, but not to com.heroku.api.Heroku.Stack.Cedar.

Parameters:

appName - See listApps() for a list of apps that can be used.

migrateTo - Stack to migrate the app to.

Returns:

A message about the migration.

listAppStacks

public List<StackInfo> listAppStacks(String appName)

Gets a list of stacks available.

Parameters:

appName - See listApps() for a list of apps that can be used.

Returns:

List of stacks available.

isMaintenanceModeEnabled

public boolean isMaintenanceModeEnabled(String appName)

Checks if maintenance mode is enabled for the given app

Parameters:

appName - See listApps() for a list of apps that can be used.

Returns:

true if maintenance mode is enabled

setMaintenanceMode

public void setMaintenanceMode(String appName,
                               boolean enable)

Sets maintenance mode for the given app

Parameters:

appName - See listApps() for a list of apps that can be used.

enable - true to enable; false to disable