README.md
1# GoVultr
2
3[](https://travis-ci.org/vultr/govultr)
4[](https://pkg.go.dev/github.com/vultr/govultr/v2)
5[](https://codecov.io/gh/vultr/govultr)
6[](https://goreportcard.com/report/github.com/vultr/govultr)
7
8The official Vultr Go client - GoVultr allows you to interact with the Vultr V2 API.
9
10GoVultr V1 that interacts with Vultr V1 API is now on the [v1 branch](https://github.com/vultr/govultr/tree/v1)
11
12## Installation
13
14```sh
15go get -u github.com/vultr/govultr/v2
16```
17
18## Usage
19
20Vultr uses a PAT (Personal Access token) to interact/authenticate with the APIs. Generate an API Key from the [API menu](https://my.vultr.com/settings/#settingsapi) in the Vultr Customer Portal.
21
22To instantiate a GoVultr client, invoke `NewClient()`. You must pass your `PAT` to an `oauth2` library to create the `*http.Client`, which configures the `Authorization` header with your PAT as the `bearer api-key`.
23
24The client has three optional parameters:
25
26- BaseUrl: Change the Vultr default base URL
27- UserAgent: Change the Vultr default UserAgent
28- RateLimit: Set a delay between calls. Vultr limits the rate of back-to-back calls. Use this parameter to avoid rate-limit errors.
29
30### Example Client Setup
31
32```go
33package main
34
35import (
36 "context"
37 "os"
38
39 "github.com/vultr/govultr/v2"
40 "golang.org/x/oauth2"
41)
42
43func main() {
44 apiKey := os.Getenv("VultrAPIKey")
45
46 config := &oauth2.Config{}
47 ctx := context.Background()
48 ts := config.TokenSource(ctx, &oauth2.Token{AccessToken: apiKey})
49 vultrClient := govultr.NewClient(oauth2.NewClient(ctx, ts))
50
51 // Optional changes
52 _ = vultrClient.SetBaseURL("https://api.vultr.com")
53 vultrClient.SetUserAgent("mycool-app")
54 vultrClient.SetRateLimit(500)
55}
56```
57
58### Example Usage
59
60Create a VPS
61
62```go
63instanceOptions := &govultr.InstanceCreateReq{
64 Label: "awesome-go-app",
65 Hostname: "awesome-go.com",
66 Backups: "enabled",
67 EnableIPv6: BoolToBoolPtr(false),
68 OsID: 362,
69 Plan: "vc2-1c-2gb",
70 Region: "ewr",
71}
72
73res, err := vultrClient.Instance.Create(context.Background(), instanceOptions)
74
75if err != nil {
76 fmt.Println(err)
77}
78```
79
80## Pagination
81
82GoVultr v2 introduces pagination for all list calls. Each list call returns a `meta` struct containing the total amount of items in the list and next/previous links to navigate the paging.
83
84```go
85// Meta represents the available pagination information
86type Meta struct {
87 Total int `json:"total"`
88 Links *Links
89}
90
91// Links represent the next/previous cursor in your pagination calls
92type Links struct {
93 Next string `json:"next"`
94 Prev string `json:"prev"`
95}
96
97```
98Pass a `per_page` value to the `list_options` struct to adjust the number of items returned per call. The default is 100 items per page and max is 500 items per page.
99
100This example demonstrates how to retrieve all of your instances, with one instance per page.
101
102```go
103listOptions := &govultr.ListOptions{PerPage: 1}
104for {
105 i, meta, err := client.Instance.List(ctx, listOptions)
106 if err != nil {
107 return nil, err
108 }
109 for _, v := range i {
110 fmt.Println(v)
111 }
112
113 if meta.Links.Next == "" {
114 break
115 } else {
116 listOptions.Cursor = meta.Links.Next
117 continue
118 }
119}
120```
121## Versioning
122
123This project follows [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/vultr/govultr/tags).
124
125## Documentation
126
127See our documentation for [detailed information about API v2](https://www.vultr.com/api/).
128
129See our [GoDoc](https://pkg.go.dev/github.com/vultr/govultr/v2) documentation for more details about this client's functionality.
130
131## Contributing
132
133Feel free to send pull requests our way! Please see the [contributing guidelines](CONTRIBUTING.md).
134
135## License
136
137This project is licensed under the MIT License - see the [LICENSE.md](LICENSE) file for details.
138
){kind=link}
){kind=link}