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