README.md

heroku-go

An API client interface for Heroku for the Go (golang) programming language.

Background

This package provides a complete interface to all of the Heroku Platform API v3
actions, and is almost entirely auto-generated based on the API's JSON Schema.
The exceptions are the files heroku.go, heroku_test.go, and app_test.go,
as well as the generator itself. All models are auto-generated by the Ruby
script in gen/gen.rb.

The client leverages Go's powerful net/http Client. That means that,
out-of-the-box, it has keep-alive support and the ability to handle many
concurrent requests from different goroutines.

You should have at least some understanding of Heroku and its
Platform API.

Installation

This package is targeted towards Go 1.2 or later, though it may work on
earlier versions as well.

Run go get github.com/bgentry/heroku-go to download, build, and install the
package.

That's it! Here is a more advanced example that also sets some options on the
new app:

name:="myapp"region:="region"// Optional values need to be provided as pointers. If a field in an option// struct is nil (not provided), the option is omitted from the API request.opts:= heroku.AppCreateOpts{Name: &name, Region: &region}
// Create an app with options set:app2, err:= client.AppCreate(&opts)
if err != nil {
// if this is a heroku.Error, it will contain details about the errorifhkerr, ok:= err.(heroku.Error); ok {
panic(fmt.Sprintf("Error id=%s message=%q", hkerr.Id, hkerr))
}
}
fmt.Printf("created app2: name=%s region=%s", app2.Name, app2.Region.Name)
// Output:// created app2: name=myapp region=eu

Optional Parameters

Many of the Heroku Platform API actions have optional parameters. For example,
when creating an app, you can either specify a custom name, or allow the API to
choose a random haiku name for your app.

Optional parameters in heroku-go are always provided to functions as a pointer
to a struct, such as AppCreateOpts for the function AppCreate(). If you do
not wish to set any optional parameters, simply provide a nil in place of the
options struct, and the options will be omitted from the API request entirely.
For any individual options that you don't want to set, simply leave them as
nil, and they will be omitted from the API request.

List Ranges & Sorting

Results from the Heroku API are paginated. You can specify a field for sorting
and adjust the maximum number of records returned by providing a ListRange to
API calls that list objects:

Documentation

Thank You

A special thanks goes out to Keith Rarick for writing
much of the base API client
as part of hk. I also want to thank the Heroku
API team for making their API available in JSON schema and for the early version
of heroics, on which this generator is
based.