Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Ruby Client for Platforms using the Add-on Platform API
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status

codename: Kaikei

The addons client is a Ruby library that creates the RESTful requests that are used to interact with the Add-on Platform API.

The Platform API provides 3 main functions for Add-ons: provisioning, deprovisioning, and plan change. Historically, the heroku module "core" was responsible for sending the appropriate messages to add-on providers and reacting correctly according to those responses. Core will still have to react to api errors, but will no longer send messages to providers.

The Addons Client represents the first attempt at having a well-defined interface between a Platform and these add-on related API interactions. It is an implementation of the following API:

Also, we have provided a command line client (the real first consumer of the API) so we could issue API requests to the add-ons app without having to fire up a console session.


make a test directory

mkdir client-test
cd client-test

make a Gemfile with the gem on github

echo "source :rubygems" > Gemfile
echo "gem 'addons-client', :git => ''" >> Gemfile

use bundler to install the Gem from github

bundle install

set up ENV

export ADDONS_API_URL=https://heroku:password@localhost:3000

it works

bundle exec addons-client  
Command must be one of: provision, deprovision, planchange    

Remember to use bundle exec to run the command line commands!

Ruby Usage

client =
 # Addons::UserError: ADDONS_API_URL must be set


client =

API Methods

client.provision! 'memcache:5mb'

client.provision! 'foo:bar', :consumer_id => '',
  :options => { :foo => 'bar', 'baz' => 'test' } 

  # => {:resource_id=>"DEADBEEF", 
  #     :config=>{"FOO_URL"=>""}, 
  #     :message=>"great success", 
  #     :provider_id=>"ABC123"} 

client.plan_change! 'ABC123', 'new_plan'

client.deprovision! 'ABC123'

Command Line Usage

export ADDONS_API_URL=http://heroku:password@localhost:3000

addons-client provision memcache:5mb --options.baz=true


addons-client provision glenntest:test 

use the resource id to interact with the add-on

addons-client plan_change 0dedb8f4-2921-42b8-81b9-a7df4c551140 test

addons-client deprovision 0dedb8f4-2921-42b8-81b9-a7df4c551140
Deprovisioned 0dedb8f4-2921-42b8-81b9-a7df4c551140 

fun with options

addons-client provision foo-bar:test --options.message='Good job'

enabling api requests

Notice the provider_id is null.
This is because we won't send live requests until we've enabled the switch.
And also because in a later story we will want to have this toggleable on a per-request basis.  

heroku config:add PROVIDER_API_ENABLED=true --app addons-staging 

it should now create a resource with a provider_id

addons-client provision foo-bar:test
Provisioned foo-bar:test

Test Usage

The client supports a mocked mode that sends no requests and returns canned responses.

Addons::Client.mock!! 'foo:bar' 
  # => {:resource_id=>"DEADBEEF", 
  #     :config=>{"FOO_URL"=>""}, 
  #     :message=>"great success", 
  #     :provider_id=>"ABC123"} 

Addons::Client.unmock!! 'foo:bar'
 # Addons::UserError: ADDONS_API_URL must be set


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
Something went wrong with that request. Please try again.