Ruby HTTP client for the Heroku API.
NOTE: v2.0.0 fixed a long-standing issue with duplicated link titles, which may break things if you were relying on the now-renamed methods.
Add this line to your application's Gemfile:
gem 'platform-api'
And then execute:
bundle
Or install it yourself as:
gem install platform-api
Jump right to the API documentation for the nitty gritty details.
The best place to start using the Heroku API is the Platform API Reference. It has detailed descriptions of the HTTP API, including general information about authentication, caching, object identifiers, rate limits, etc. It also includes detailed information about each supported resource and the actions available for them.
The table of contents lists all the resources that are supported, such as App, Add-on, Config Vars, Formation, etc. Each resource includes detailed information about the support actions. For example, the Formation resource has Info, List, Batch update, and Update actions.
Resources and their related actions are available as methods on the client. When the URL for an action includes parameters they're passed as arguments to the method. When the request expects a request payload it's passed as a Hash in the final argument to the method.
For example, to get information about the web formation on the sushi app
you'd invoke heroku.formation.info('sushi', 'web') and it would return a
Ruby object that matches the one given in the response example.
The API documentation contains a description of all available resources and methods.
The client uses Excon under the hood and
raises Excon::Error exceptions when errors occur. You can catch specific
Excon error types if you want.
Let's go through an example of creating an app and using the API to work with
it. The first thing you need is a client setup with an OAuth token. You can
create an OAuth token using the heroku-oauth toolbelt plugin:
$ heroku plugins:install heroku-cli-oauth
$ heroku authorizations:create -d "Platform API example token"
Created OAuth authorization.
ID: 2f01aac0-e9d3-4773-af4e-3e510aa006ca
Description: Platform API example token
Scope: global
Token: e7dd6ad7-3c6a-411e-a2be-c9fe52ac7ed2Use the Token value when instantiating a client:
require 'platform-api'
heroku = PlatformAPI.connect_oauth('e7dd6ad7-3c6a-411e-a2be-c9fe52ac7ed2')The OAuth article has more information about OAuth tokens, including how to create tokens with specific scopes.
Now let's create an app:
heroku.app.create({})
=> {"id"=>22979756,
"name"=>"floating-retreat-4255",
"dynos"=>0,
"workers"=>0,
"repo_size"=>nil,
"slug_size"=>nil,
"stack"=>"cedar",
"requested_stack"=>nil,
"create_status"=>"complete",
"repo_migrate_status"=>"complete",
"owner_delinquent"=>false,
"owner_email"=>"[email protected]",
"owner_name"=>nil,
"domain_name"=>
{"id"=>nil,
"app_id"=>22979756,
"domain"=>"floating-retreat-4255.herokuapp.com",
"base_domain"=>"herokuapp.com",
"created_at"=>nil,
"default"=>true,
"updated_at"=>nil},
"web_url"=>"http://floating-retreat-4255.herokuapp.com/",
"git_url"=>"[email protected]:floating-retreat-4255.git",
"buildpack_provided_description"=>nil,
"region"=>"us",
"created_at"=>"2014/03/12 16:44:09 -0700",
"archived_at"=>nil,
"released_at"=>"2014/03/12 16:44:10 -0700",
"updated_at"=>"2014/03/12 16:44:10 -0700"}We can read the same information back with the info method.
heroku.app.info('floating-retreat-4255')
=> {"id"=>22979756,
"name"=>"floating-retreat-4255",
"dynos"=>0,
"workers"=>0,
"repo_size"=>nil,
"slug_size"=>nil,
"stack"=>"cedar",
"requested_stack"=>nil,
"create_status"=>"complete",
"repo_migrate_status"=>"complete",
"owner_delinquent"=>false,
"owner_email"=>"[email protected]",
"owner_name"=>nil,
"domain_name"=>
{"id"=>nil,
"app_id"=>22979756,
"domain"=>"floating-retreat-4255.herokuapp.com",
"base_domain"=>"herokuapp.com",
"created_at"=>nil,
"default"=>true,
"updated_at"=>nil},
"web_url"=>"http://floating-retreat-4255.herokuapp.com/",
"git_url"=>"[email protected]:floating-retreat-4255.git",
"buildpack_provided_description"=>nil,
"region"=>"us",
"created_at"=>"2014/03/12 16:44:09 -0700",
"archived_at"=>nil,
"released_at"=>"2014/03/12 16:44:12 -0700",
"updated_at"=>"2014/03/12 16:44:12 -0700"}Let's add a Heroku PostgreSQL database to our app now:
heroku.addon.create('floating-retreat-4255', {'plan' => 'heroku-postgresql:hobby-dev'})
=> {"config_vars"=>["HEROKU_POSTGRESQL_COBALT_URL"],
"created_at"=>"2014-03-13T00:28:55Z",
"id"=>"79a0c826-06be-4dcd-8bb5-f2c1b1bc2beb",
"name"=>"heroku-postgresql-cobalt",
"plan"=>
{"id"=>"95a1ce4c-c651-45dc-aaee-79b4603e76b7",
"name"=>"heroku-postgresql:dev"},
"provider_id"=>"[email protected]",
"updated_at"=>"2014-03-13T00:28:55Z"}Excellent! That will have added a config var which we can now see:
heroku.config_var.info_for_app('floating-retreat-4255')
=> {"HEROKU_POSTGRESQL_COBALT_URL"=>"postgres://<redacted>"}And there we go, we have the config var. Let's set an additional config var, which will also demonstrate how to make a request that needs a payload:
heroku.config_var.update('floating-retreat-4255', {'MYAPP' => 'ROCKS'})
=> {"HEROKU_POSTGRESQL_COBALT_URL"=>"postgres://<redacted>",
"MYAPP"=>"ROCKS"}As you can see, any action that needs a request body takes it as a plain Ruby object, as the final parameter of the method call.
Using the same principle you can even pass in a specific version of PostgreSQL at the time of creation:
heroku.addon.create('floating-retreat-4255', {'plan' => 'heroku-postgresql:dev', 'config' => {'version' => '9.4'})Make sure to use the correct version. If the version is incorrect or unsupported, it will just error out.
Let's continue by deploying a sample app. We'll use the Geosockets example app:
$ git clone https://github.com/heroku-examples/geosockets.git
Cloning into 'geosockets'...
remote: Reusing existing pack: 489, done.
remote: Total 489 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (489/489), 1.95 MiB | 1.14 MiB/s, done.
Resolving deltas: 100% (244/244), done.
Checking connectivity... done.
$ cd geosockets
$ git remote add heroku [email protected]:floating-retreat-4255.git
$ heroku labs:enable websockets
$ heroku addons:add openredis:micro # $10/month
Adding openredis:micro on floating-retreat-4255... done, v10 ($10/mo)
Use `heroku addons:docs openredis` to view documentation.
$ git push heroku master
Initializing repository, done.
Counting objects: 489, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (229/229), done.
Writing objects: 100% (489/489), 1.95 MiB | 243.00 KiB/s, done.
Total 489 (delta 244), reused 489 (delta 244)
8< snip 8<We can now use the API to see our web process running:
heroku.formation.list('floating-retreat-4255')
=> [{"command"=>"coffee index.coffee",
"created_at"=>"2014-03-13T04:13:37Z",
"id"=>"f682b260-8089-4e18-b792-688cc02bf923",
"type"=>"web",
"quantity"=>1,
"size"=>"Standard-1X",
"updated_at"=>"2014-03-13T04:13:37Z"}]Let's change web process to run on a 2X dyno:
heroku.formation.batch_update('floating-retreat-4255',
{"updates" => [{"process" => "web",
"quantity" => 1,
"size" => "Standard-2X"}]})
=> [{"command"=>"coffee index.coffee",
"created_at"=>"2014-03-13T04:13:37Z",
"id"=>"f682b260-8089-4e18-b792-688cc02bf923",
"type"=>"web",
"quantity"=>1,
"size"=>"Standard-2X",
"updated_at"=>"2014-03-13T04:22:15Z"}]We could have included a number of different kinds of processes in the last command. We can use the singular update action to modify a single formation type:
heroku.formation.update('floating-retreat-4255', 'web', {"size" => "Standard-1X"})
=> {"command"=>"coffee index.coffee",
"created_at"=>"2014-03-13T04:13:37Z",
"id"=>"f682b260-8089-4e18-b792-688cc02bf923",
"type"=>"web",
"quantity"=>1,
"size"=>"Standard-1X",
"updated_at"=>"2014-03-13T04:24:46Z"}Hopefully this has given you a taste of how the client works. If you have questions please feel free to file issues.
Sometimes it helps to see more information about the requests flying by. You
can start your program or an irb session with the EXCON_DEBUG=1
environment variable to cause request and response data to be written to
STDERR.
The various connect methods take an options hash that you can use to include
custom headers to include with every request:
client = PlatformAPI.connect('my-api-key', default_headers: {'Foo' => 'Bar'})By default, the platform-api will cache data in ~/.heroics/platform-api.
Use a different caching by passing in the Moneta
instance you want to use:
client = PlatformAPI.connect('my-api-key', cache: Moneta.new(:Memory))Connect to a different host by passing a url option:
client = PlatformAPI.connect('my-api-key', url: 'https://api.example.com')Rate throttling capability is inclued in PlatformAPI v2.3.0, but is disabled by default. The following section describes the behavior of the PlatformAPI gem v3.0.0+. To enable rate throttling logic, upgrade to the latest released version.
By default client requests from this library will respect Heroku's rate-limiting. The client can make as many requests as possible until Heroku's server says that it has gone over. Once a request has been rate-limited the client will sleep and then retry the request again. This process will repeat until the request is successful.
Once a single request has been rate-limited, the client will auto-tune a sleep value so that future requests are less likely to be rate-limited by the server.
Rate throttle strategies are provided by the Rate Throttle Client gem. By default the RateThrottleClient::ExponentialIncreaseProportionalRemainingDecrease strategy is used.
To disable this retry-and-sleep behavior you can change the rate throttling strategy to any object that responds to call and yields to a block:
PlatformAPI.rate_throttle = ->(&block) { block.call }
# or
PlatformAPI.rate_throttle = RateThrottleClient::Null.newBy default rate throttling will log to STDOUT when the sleep/retry behavior is triggered:
RateThrottleClient: sleep_for=0.8
To add your own custom logging, for example to Librato or Honeycomb, you can configure logging by providing an object that responds to call and takes one argument:
PlatformAPI.rate_throttle.log = ->(info) {
# Your logic here
puts info.sleep_for
puts info.request
}Generate a new client from the Heroku Platform API JSON schema:
rake build
Remember to commit and push the changes to Github.
- This project follows semver from version 1.0.0. Please be sure to keep this in mind if you're the project maintainer.
- Be sure to run the very basic acceptance rspecs. The rspecs will attempt
to parse your oauth token for
api.heroku.comfrom your.netrc. You can optionally use theOAUTH_TOKENandACCOUNT_EMAILenvironment variables. They don't mutate anything but they might in the future. - Bump the version in
lib/platform-api/version.rb bundle installto update Gemfile.lock- `git commit -m 'vX.Y.Z' to stage the version and Gemfile.lock changes
rake releaseto push git changes and to release to Rubygems
Build documentation with:
rake yard
And then visit doc/index.html to read it. Alternately, build and publish
it to Github Pages in one step with:
rake publish_docs
You can see it live on Github Pages.
- Fork the repository.
- Create your feature branch:
git checkout -b my-new-feature - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Create new pull request.
The tests make live network calls so you'll need to ensure that you're logged into your Heroku account. You'll also need an application that uses a set of Heroku's features, if you don't have one you can create one. E.g.
$ git clone https://github.com/heroku/ruby-getting-started.git
$ cd ruby-getting-started/
$ heroku create <memorable-name-here>
$ heroku webhooks:add -i api:dyno -l notify -u https://example.com/hooks
$ git push heroku master
Now you can specify your app name while you run tests:
$ TEST_APP_NAME="<memorable-name-here>" rspec ./spec
If you run tests without specifying a TEST_APP_NAME then an app will be created and deployed under your user account.