Permalink
Browse files

Use pointers to option structs.

Also added some doc improvements. Fixes #3.
  • Loading branch information...
1 parent 342c66a commit 2039cc251b04650f5bef3147f155bc8f6a82f7bd @bgentry committed Dec 19, 2013
Showing with 87 additions and 41 deletions.
  1. +29 −5 README.md
  2. +2 −2 account.go
  3. +2 −2 addon.go
  4. +4 −4 app.go
  5. +2 −2 app_test.go
  6. +2 −2 collaborator.go
  7. +26 −4 doc.go
  8. +2 −2 dyno.go
  9. +2 −2 formation.go
  10. +4 −4 gen/gen.rb
  11. +2 −2 log_session.go
  12. +2 −2 oauth_authorization.go
  13. +2 −2 oauth_client.go
  14. +2 −2 release.go
  15. +2 −2 slug.go
  16. +2 −2 ssl_endpoint.go
View
@@ -17,6 +17,9 @@ 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][platform-api].
+
## Installation
This package is targeted towards Go 1.2 or later, though it may work on
@@ -35,15 +38,20 @@ import (
)
```
-Then create a Client object and make calls to it:
+Then create a `Client` object and make calls to it:
```go
client := heroku.Client{Username: "email@me.com", Password: "my-api-key"}
-app, err := client.AppCreate(heroku.AppCreateOpts{})
+
+// 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
@@ -53,9 +61,12 @@ new app:
name := "myapp"
region := "region"
-// optional values need to be pointers
+// 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}
-app2, err := client.AppCreate(opts) // Create an app with options set
+
+// 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 {
@@ -65,12 +76,25 @@ if err != nil {
fmt.Printf("created app2: name=%s region=%s", app2.Name, app2.Region.Name)
// Output:
-// created app1: name=dodging-samurai-42 region=us
// 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.
+
## Documentation
More detailed documentation is available on [godoc][godoc].
[godoc]: https://godoc.org/github.com/bgentry/heroku-go "heroku-go on Godoc.org"
+[platform-api]: https://devcenter.heroku.com/articles/platform-api-reference "Heroku Platform API"
View
@@ -47,8 +47,8 @@ func (c *Client) AccountInfo() (*Account, error) {
//
// accountIdentity is the unique identifier of the Account. password is the
// current password on the account. options is the struct of optional parameters
-// for this call.
-func (c *Client) AccountUpdate(password string, options AccountUpdateOpts) (*Account, error) {
+// for this action.
+func (c *Client) AccountUpdate(password string, options *AccountUpdateOpts) (*Account, error) {
params := struct {
Password string `json:"password"`
AllowTracking *bool `json:"allow_tracking,omitempty"`
View
@@ -33,8 +33,8 @@ type Addon struct {
//
// appIdentity is the unique identifier of the addon's app. plan is the unique
// identifier of this plan or unique name of this plan. options is the struct of
-// optional parameters for this call.
-func (c *Client) AddonCreate(appIdentity string, plan string, options AddonCreateOpts) (*Addon, error) {
+// optional parameters for this action.
+func (c *Client) AddonCreate(appIdentity string, plan string, options *AddonCreateOpts) (*Addon, error) {
params := struct {
Plan string `json:"plan"`
Config *map[string]string `json:"config,omitempty"`
View
@@ -68,8 +68,8 @@ type App struct {
// Create a new app.
//
-// options is the struct of optional parameters for this call.
-func (c *Client) AppCreate(options AppCreateOpts) (*App, error) {
+// options is the struct of optional parameters for this action.
+func (c *Client) AppCreate(options *AppCreateOpts) (*App, error) {
var appRes App
return &appRes, c.Post(&appRes, "/apps", options)
}
@@ -120,8 +120,8 @@ func (c *Client) AppList(lr *ListRange) ([]App, error) {
// Update an existing app.
//
// appIdentity is the unique identifier of the App. options is the struct of
-// optional parameters for this call.
-func (c *Client) AppUpdate(appIdentity string, options AppUpdateOpts) (*App, error) {
+// optional parameters for this action.
+func (c *Client) AppUpdate(appIdentity string, options *AppUpdateOpts) (*App, error) {
var appRes App
return &appRes, c.Patch(&appRes, "/apps/"+appIdentity, options)
}
View
@@ -167,7 +167,7 @@ func TestAppCreateSuccess(t *testing.T) {
ts, handler, c := newTestServerAndClient(t, appCreateRequest)
defer ts.Close()
- app, err := c.AppCreate(appCreateRequestOptions)
+ app, err := c.AppCreate(&appCreateRequestOptions)
if err != nil {
t.Fatal(err)
}
@@ -250,7 +250,7 @@ func TestAppUpdateSuccess(t *testing.T) {
ts, handler, c := newTestServerAndClient(t, appUpdateRequest)
defer ts.Close()
- app, err := c.AppUpdate("example", appUpdateRequestOptions)
+ app, err := c.AppUpdate("example", &appUpdateRequestOptions)
if err != nil {
t.Fatal(err)
}
View
@@ -31,8 +31,8 @@ type Collaborator struct {
//
// appIdentity is the unique identifier of the collaborator's app. user is the
// unique email address of account or unique identifier of an account. options
-// is the struct of optional parameters for this call.
-func (c *Client) CollaboratorCreate(appIdentity string, user string, options CollaboratorCreateOpts) (*Collaborator, error) {
+// is the struct of optional parameters for this action.
+func (c *Client) CollaboratorCreate(appIdentity string, user string, options *CollaboratorCreateOpts) (*Collaborator, error) {
params := struct {
User string `json:"user"`
Silent *bool `json:"silent,omitempty"`
View
@@ -17,6 +17,9 @@ 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:
+https://devcenter.heroku.com/articles/platform-api-reference
+
Installation
This package is targeted towards Go 1.2 or later, though it may work on
@@ -36,21 +39,29 @@ To use the client, first add it to your Go file's imports list:
Then create a Client object and make calls to it:
client := heroku.Client{Username: "email@me.com", Password: "my-api-key"}
- app, err := client.AppCreate(heroku.AppCreateOpts{})
+
+ // 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 pointers
+ // 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}
- app2, err := client.AppCreate(opts) // Create an app with options set
+
+ // 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 {
@@ -60,8 +71,19 @@ new app:
fmt.Printf("created app2: name=%s region=%s", app2.Name, app2.Region.Name)
// Output:
- // created app1: name=dodging-samurai-42 region=us
// 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.
*/
package heroku
View
@@ -48,8 +48,8 @@ type Dyno struct {
//
// appIdentity is the unique identifier of the dyno's app. command is the
// command used to start this process. options is the struct of optional
-// parameters for this call.
-func (c *Client) DynoCreate(appIdentity string, command string, options DynoCreateOpts) (*Dyno, error) {
+// parameters for this action.
+func (c *Client) DynoCreate(appIdentity string, command string, options *DynoCreateOpts) (*Dyno, error) {
params := struct {
Command string `json:"command"`
Attach *bool `json:"attach,omitempty"`
View
@@ -94,8 +94,8 @@ type FormationBatchUpdateOpts struct {
//
// appIdentity is the unique identifier of the formation's app.
// formationIdentity is the unique identifier of the Formation. options is the
-// struct of optional parameters for this call.
-func (c *Client) FormationUpdate(appIdentity string, formationIdentity string, options FormationUpdateOpts) (*Formation, error) {
+// struct of optional parameters for this action.
+func (c *Client) FormationUpdate(appIdentity string, formationIdentity string, options *FormationUpdateOpts) (*Formation, error) {
var formationRes Formation
return &formationRes, c.Patch(&formationRes, "/apps/"+appIdentity+"/formation/"+formationIdentity, options)
}
View
@@ -370,7 +370,7 @@ def func_args_from_model_and_link(definition, modelname, link)
args << "#{variablecase(propname)} #{type}"
end
end
- args << "options #{titlecase(modelname)}#{link["rel"].capitalize}Opts" unless optional.empty?
+ args << "options *#{titlecase(modelname)}#{link["rel"].capitalize}Opts" unless optional.empty?
end
if "instances" == link["rel"]
@@ -438,7 +438,7 @@ def func_arg_comments_from_model_and_link(definition, modelname, link)
raise "Didn't expect 3 rpresults"
end
end
- args << "options is the struct of optional parameters for this call." unless optional_keys.empty?
+ args << "options is the struct of optional parameters for this action." unless optional_keys.empty?
end
if "instances" == link["rel"]
@@ -447,10 +447,10 @@ def func_arg_comments_from_model_and_link(definition, modelname, link)
case link["rel"]
when "create"
- ["options is the struct of optional parameters for this call."]
+ ["options is the struct of optional parameters for this action."]
when "update"
["#{variablecase(modelname)}Identity is the unique identifier of the #{titlecase(modelname)}.",
- "options is the struct of optional parameters for this call."]
+ "options is the struct of optional parameters for this action."]
when "destroy", "self"
["#{variablecase(modelname)}Identity is the unique identifier of the #{titlecase(modelname)}."]
when "instances"
View
@@ -26,8 +26,8 @@ type LogSession struct {
// Create a new log session.
//
// appIdentity is the unique identifier of the log-session's app. options is the
-// struct of optional parameters for this call.
-func (c *Client) LogSessionCreate(appIdentity string, options LogSessionCreateOpts) (*LogSession, error) {
+// struct of optional parameters for this action.
+func (c *Client) LogSessionCreate(appIdentity string, options *LogSessionCreateOpts) (*LogSession, error) {
var logSessionRes LogSession
return &logSessionRes, c.Post(&logSessionRes, "/apps/"+appIdentity+"/log-sessions", options)
}
@@ -56,8 +56,8 @@ type OAuthAuthorization struct {
// Create a new OAuth authorization.
//
// scope is the The scope of access OAuth authorization allows. options is the
-// struct of optional parameters for this call.
-func (c *Client) OAuthAuthorizationCreate(scope []string, options OAuthAuthorizationCreateOpts) (*OAuthAuthorization, error) {
+// struct of optional parameters for this action.
+func (c *Client) OAuthAuthorizationCreate(scope []string, options *OAuthAuthorizationCreateOpts) (*OAuthAuthorization, error) {
params := struct {
Scope []string `json:"scope"`
Client *string `json:"client,omitempty"`
View
@@ -86,8 +86,8 @@ func (c *Client) OAuthClientList(lr *ListRange) ([]OAuthClient, error) {
// Update OAuth client
//
// oauthClientIdentity is the unique identifier of the OAuthClient. options is
-// the struct of optional parameters for this call.
-func (c *Client) OAuthClientUpdate(oauthClientIdentity string, options OAuthClientUpdateOpts) (*OAuthClient, error) {
+// the struct of optional parameters for this action.
+func (c *Client) OAuthClientUpdate(oauthClientIdentity string, options *OAuthClientUpdateOpts) (*OAuthClient, error) {
var oauthClientRes OAuthClient
return &oauthClientRes, c.Patch(&oauthClientRes, "/oauth/clients/"+oauthClientIdentity, options)
}
View
@@ -69,8 +69,8 @@ func (c *Client) ReleaseList(appIdentity string, lr *ListRange) ([]Release, erro
//
// appIdentity is the unique identifier of the release's app. slug is the unique
// identifier of slug. options is the struct of optional parameters for this
-// call.
-func (c *Client) ReleaseCreate(appIdentity string, slug string, options ReleaseCreateOpts) (*Release, error) {
+// action.
+func (c *Client) ReleaseCreate(appIdentity string, slug string, options *ReleaseCreateOpts) (*Release, error) {
params := struct {
Slug string `json:"slug"`
Description *string `json:"description,omitempty"`
View
@@ -44,8 +44,8 @@ func (c *Client) SlugInfo(appIdentity string, slugIdentity string) (*Slug, error
//
// appIdentity is the unique identifier of the slug's app. processTypes is the
// hash mapping process type names to their respective command. options is the
-// struct of optional parameters for this call.
-func (c *Client) SlugCreate(appIdentity string, processTypes map[string]string, options SlugCreateOpts) (*Slug, error) {
+// struct of optional parameters for this action.
+func (c *Client) SlugCreate(appIdentity string, processTypes map[string]string, options *SlugCreateOpts) (*Slug, error) {
params := struct {
ProcessTypes map[string]string `json:"process_types"`
Commit *string `json:"commit,omitempty"`
View
@@ -89,8 +89,8 @@ func (c *Client) SslEndpointList(appIdentity string, lr *ListRange) ([]SslEndpoi
//
// appIdentity is the unique identifier of the ssl-endpoint's app.
// sslEndpointIdentity is the unique identifier of the SslEndpoint. options is
-// the struct of optional parameters for this call.
-func (c *Client) SslEndpointUpdate(appIdentity string, sslEndpointIdentity string, options SslEndpointUpdateOpts) (*SslEndpoint, error) {
+// the struct of optional parameters for this action.
+func (c *Client) SslEndpointUpdate(appIdentity string, sslEndpointIdentity string, options *SslEndpointUpdateOpts) (*SslEndpoint, error) {
var sslEndpointRes SslEndpoint
return &sslEndpointRes, c.Patch(&sslEndpointRes, "/apps/"+appIdentity+"/ssl-endpoints/"+sslEndpointIdentity, options)
}

0 comments on commit 2039cc2

Please sign in to comment.