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
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