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