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
30package main
31
32import (
33	"context"
34	"github.com/digitalocean/godo"
35	"golang.org/x/oauth2"
36)
37
38const (
39    pat = "mytoken"
40)
41
42type TokenSource struct {
43	AccessToken string
44}
45
46func (t *TokenSource) Token() (*oauth2.Token, error) {
47	token := &oauth2.Token{
48		AccessToken: t.AccessToken,
49	}
50	return token, nil
51}
52
53func main() {
54	tokenSource := &TokenSource{
55		AccessToken: pat,
56	}
57
58	oauthClient := oauth2.NewClient(context.Background(), tokenSource)
59	client := godo.NewClient(oauthClient)
60}
61```
62
63## Examples
64
65
66To create a new Droplet:
67
68```go
69dropletName := "super-cool-droplet"
70
71createRequest := &godo.DropletCreateRequest{
72    Name:   dropletName,
73    Region: "nyc3",
74    Size:   "s-1vcpu-1gb",
75    Image: godo.DropletCreateImage{
76        Slug: "ubuntu-14-04-x64",
77    },
78}
79
80ctx := context.TODO()
81
82newDroplet, _, err := client.Droplets.Create(ctx, createRequest)
83
84if err != nil {
85    fmt.Printf("Something bad happened: %s\n\n", err)
86    return err
87}
88```
89
90### Pagination
91
92If a list of items is paginated by the API, you must request pages individually. For example, to fetch all Droplets:
93
94```go
95func DropletList(ctx context.Context, client *godo.Client) ([]godo.Droplet, error) {
96    // create a list to hold our droplets
97    list := []godo.Droplet{}
98
99    // create options. initially, these will be blank
100    opt := &godo.ListOptions{}
101    for {
102        droplets, resp, err := client.Droplets.List(ctx, opt)
103        if err != nil {
104            return nil, err
105        }
106
107        // append the current page's droplets to our list
108        for _, d := range droplets {
109            list = append(list, d)
110        }
111
112        // if we are at the last page, break out the for loop
113        if resp.Links == nil || resp.Links.IsLastPage() {
114            break
115        }
116
117        page, err := resp.Links.CurrentPage()
118        if err != nil {
119            return nil, err
120        }
121
122        // set the page we want for the next request
123        opt.Page = page + 1
124    }
125
126    return list, nil
127}
128```
129
130## Versioning
131
132Each version of the client is tagged and the version is updated accordingly.
133
134Since Go does not have a built-in versioning, a package management tool is
135recommended - a good one that works with git tags is
136[gopkg.in](http://labix.org/gopkg.in).
137
138To see the list of past versions, run `git tag`.
139
140
141## Documentation
142
143For a comprehensive list of examples, check out the [API documentation](https://developers.digitalocean.com/documentation/v2/).
144
145For details on all the functionality in this library, see the [GoDoc](http://godoc.org/github.com/digitalocean/godo) documentation.
146
147
148## Contributing
149
150We love pull requests! Please see the [contribution guidelines](CONTRIBUTING.md).
151