README.md
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
121Some endpoints offer token based pagination. For example, to fetch all Registry Repositories:
122
123```go
124func ListRepositoriesV2(ctx context.Context, client *godo.Client, registryName string) ([]*godo.RepositoryV2, error) {
125 // create a list to hold our registries
126 list := []*godo.RepositoryV2{}
127
128 // create options. initially, these will be blank
129 opt := &godo.TokenListOptions{}
130 for {
131 repositories, resp, err := client.Registry.ListRepositoriesV2(ctx, registryName, opt)
132 if err != nil {
133 return nil, err
134 }
135
136 // append the current page's registries to our list
137 list = append(list, repositories...)
138
139 // if we are at the last page, break out the for loop
140 if resp.Links == nil || resp.Links.IsLastPage() {
141 break
142 }
143
144 // grab the next page token
145 nextPageToken, err := resp.Links.NextPageToken()
146 if err != nil {
147 return nil, err
148 }
149
150 // provide the next page token for the next request
151 opt.Token = nextPageToken
152 }
153
154 return list, nil
155}
156```
157
158## Versioning
159
160Each version of the client is tagged and the version is updated accordingly.
161
162To see the list of past versions, run `git tag`.
163
164
165## Documentation
166
167For a comprehensive list of examples, check out the [API documentation](https://docs.digitalocean.com/reference/api/api-reference/#tag/SSH-Keys).
168
169For details on all the functionality in this library, see the [GoDoc](http://godoc.org/github.com/digitalocean/godo) documentation.
170
171
172## Contributing
173
174We love pull requests! Please see the [contribution guidelines](CONTRIBUTING.md).
175