bgentry/heroku-go

Golang Heroku API Client

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.

Getting Started

To use the client, first add it to your Go file's imports list:

import (
  "github.com/bgentry/heroku-go"
)

Then create a Client object and make calls to it:

client := heroku.Client{Username: "[email protected]", Password: "my-api-key"}

// pass nil for options if you don't need to set any optional params
app, err := client.AppCreate(nil)
if err != nil {
  panic(err)
}
fmt.Println("Created", app.Name)

// Output:
// Created dodging-samurai-42

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 error
  if hkerr, 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:

apps, err = client.AppList(&heroku.ListRange{Field: "name", Max: 1000})

Note Field is required when setting any range options.

Documentation

More detailed documentation is available on godoc.

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.

heroku-go's Issues

Add String() method to types to satisfy fmt.Stringer interface

Make it so types can be easily printed with fmt.

Opts should be passed as pointers

Consider the simple example of app creation with no options set. Here's how it currently works:

app, err := client.AppCreate(heroku.AppCreateOpts{})

That's because the function signature is:

func (c *Client) AppCreate(options AppCreateOpts) (*App, error) { ... }

If the options var was a *AppCreateOpts instead of AppCreateOpts, the internal logic to the function would be a bit more complicated (it would need to detect if options was nil or not) but the UX would probably be cleaner:

app, err := client.AppCreate(nil)

Which makes the options truly optional.

Authentication types

The Octokit go library has the concept of Auth types, examples right now being Basic, Token and Netrc.

What do you think about refactoring the Username and Password out of the Client struct and using a similar approach, adding an AuthMethod to it:

type Client struct {
        [...]

        // The URL of the Heroku API to communicate with. Defaults to
        // "https://api.heroku.com".
        URL string

        // Authorization method (Basic, Netrc, Token)
        AuthMethod   AuthMethod

        // UserAgent to be provided in API requests. Set to DefaultUserAgent if not
        // specified.
        UserAgent string
        [...]
}

That would support initializing clients like so:

client := heroku.Client{AuthMethod: NetrcAuth}
client := heroku.Client{AuthMethod: BasicAuth{Username: "[email protected]", Password: "my-api-key"}}

slugs: ability to specify blob

The Platform API docs demonstrate POSTing to the slugs API specifying a blob: https://devcenter.heroku.com/articles/platform-api-deploying-slugs#publish-to-the-platform. heroku-go doesn't expose the blob as an option in SlugCreateOpts, only commit hash.

Remaining uses of os.Stderr should use PrintError()

runApps() prints directly to os.Stderr. It should use the PrintError() function instead for colorizing and prefixing.

Bulk Resource

This is partly a reminder to myself, but also a note to you, that this package is missing support for build.

I'll try and get to this, but its a hack project so I'm just doing stuff via net/http for now.

Builds

Hello,

I noticed the current API does not encompass the builds API.
I tried to generate it using gen.rb but it fails with the most up-to-date schema.
Any way I can help? :)

OrganizationMemberDelete function improperly generated

On line 48 of organization_member.go, the function takes two string parameters organizationIdentity and organizationMemberIdentity. Both should be used to form the URL. Line 49 should read:

return c.Delete("/organizations/" + organizationIdentity + "/members/" + organizationMemberIdentity)

Incompatible with current godep version

$ godep version
godep v79 (linux/amd64/go1.8)

$ godep get github.com/bgentry/heroku-go
godep: outdated Godeps missing source code

This dependency list was created with an old version of godep.

To work around this, you have two options:

1. Run 'godep restore', and try again.
2. Ask the maintainer to switch to a newer version of godep,
   then try again with the updated package.
   godep: exit status 1

Build + Build Result resources

Any plans to add these?

https://devcenter.heroku.com/articles/platform-api-reference#build-result

Generator doesn't respect method specified for link["rel"]

Given the following snippet from the schema, the generator would be expected to call c.Put:

      "links": [
        {
          "method": "PUT",
          "rel": "create",
          ...
        }
      ]

However, link["rel"] = create is hardcoded to c.Post:

https://github.com/bgentry/heroku-go/blob/master/gen/gen.rb#L73-L78

Rework generator to use compiled JSON schema

The generator currently works off of per-resource JSON schema files. These files are part of the API repo but are not public.

I should rework this so that it can generate off of a single schema.jsonfile that includes all resources. It should work on a file of the format returned by the API:

$ curl https://api.heroku.com/schema -H "Accept: application/vnd.heroku+json; version=3" > schema.json