README.md
1[![Build Status](https://travis-ci.org/digitalocean/godo.svg)](https://travis-ci.org/digitalocean/godo)
2
3# Godo
4
5Godo is a Go client library for accessing the DigitalOcean V2 API.
6
7You can view the client API docs here: [http://godoc.org/github.com/digitalocean/godo](http://godoc.org/github.com/digitalocean/godo)
8
9You can view DigitalOcean API docs here: [https://developers.digitalocean.com/documentation/v2/](https://developers.digitalocean.com/documentation/v2/)
10
11
12## Usage
13
14```go
15import "github.com/digitalocean/godo"
16```
17
18Create a new DigitalOcean client, then use the exposed services to
19access different parts of the DigitalOcean API.
20
21### Authentication
22
23Currently, Personal Access Token (PAT) is the only method of
24authenticating with the API. You can manage your tokens
25at the DigitalOcean Control Panel [Applications Page](https://cloud.digitalocean.com/settings/applications).
26
27You can then use your token to create a new client:
28
29```go
30import "golang.org/x/oauth2"
31
32pat := "mytoken"
33type TokenSource struct {
34 AccessToken string
35}
36
37func (t *TokenSource) Token() (*oauth2.Token, error) {
38 token := &oauth2.Token{
39 AccessToken: t.AccessToken,
40 }
41 return token, nil
42}
43
44tokenSource := &TokenSource{
45 AccessToken: pat,
46}
47oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
48client := godo.NewClient(oauthClient)
49```
50
51## Examples
52
53
54To create a new Droplet:
55
56```go
57dropletName := "super-cool-droplet"
58
59createRequest := &godo.DropletCreateRequest{
60 Name: dropletName,
61 Region: "nyc3",
62 Size: "512mb",
63 Image: godo.DropletCreateImage{
64 Slug: "ubuntu-14-04-x64",
65 },
66}
67
68newDroplet, _, err := client.Droplets.Create(createRequest)
69
70if err != nil {
71 fmt.Printf("Something bad happened: %s\n\n", err)
72 return err
73}
74```
75
76### Pagination
77
78If a list of items is paginated by the API, you must request pages individually. For example, to fetch all Droplets:
79
80```go
81func DropletList(client *godo.Client) ([]godo.Droplet, error) {
82 // create a list to hold our droplets
83 list := []godo.Droplet{}
84
85 // create options. initially, these will be blank
86 opt := &godo.ListOptions{}
87 for {
88 droplets, resp, err := client.Droplets.List(opt)
89 if err != nil {
90 return nil, err
91 }
92
93 // append the current page's droplets to our list
94 for _, d := range droplets {
95 list = append(list, d)
96 }
97
98 // if we are at the last page, break out the for loop
99 if resp.Links == nil || resp.Links.IsLastPage() {
100 break
101 }
102
103 page, err := resp.Links.CurrentPage()
104 if err != nil {
105 return nil, err
106 }
107
108 // set the page we want for the next request
109 opt.Page = page + 1
110 }
111
112 return list, nil
113}
114```
115
116## Versioning
117
118Each version of the client is tagged and the version is updated accordingly.
119
120Since Go does not have a built-in versioning, a package management tool is
121recommended - a good one that works with git tags is
122[gopkg.in](http://labix.org/gopkg.in).
123
124To see the list of past versions, run `git tag`.
125
126
127## Documentation
128
129For a comprehensive list of examples, check out the [API documentation](https://developers.digitalocean.com/documentation/v2/).
130
131For details on all the functionality in this library, see the [GoDoc](http://godoc.org/github.com/digitalocean/godo) documentation.
132
133
134## Contributing
135
136We love pull requests! Please see the [contribution guidelines](CONTRIBUTING.md).
137