API documentation

Usage guide

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.

Handling errors

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.

A real world example

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:

Hopefully this has given you a taste of how the client works. If you have
questions please feel free to file issues.

Debugging

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.

Passing custom headers

The various connect methods take an options hash that you can use to include
custom headers to include with every request:

Connecting to a different host

Rate throttling

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:

Building and releasing

Generate a new client

Release a new gem

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.com from your .netrc. You can
optionally use the OAUTH_TOKEN and ACCOUNT_EMAIL environment variables.
They don't mutate anything but they might in the future.

Bump the version in lib/platform-api/version.rb

bundle install to update Gemfile.lock

`git commit -m 'vX.Y.Z' to stage the version and Gemfile.lock changes

rake release to push git changes and to release to Rubygems

Building API documentation

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:

Testing

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.