Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vultr/govultr
Vultr Go API client
https://github.com/vultr/govultr
api go golang vultr vultr-api
Last synced: 7 days ago
JSON representation
Vultr Go API client
- Host: GitHub
- URL: https://github.com/vultr/govultr
- Owner: vultr
- License: mit
- Created: 2019-05-03T17:13:37.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-12-17T21:53:10.000Z (22 days ago)
- Last Synced: 2024-12-26T00:01:43.629Z (14 days ago)
- Topics: api, go, golang, vultr, vultr-api
- Language: Go
- Size: 858 KB
- Stars: 234
- Watchers: 8
- Forks: 56
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-list - govultr
README
# GoVultr
[](https://github.com/vultr/govultr/actions/workflows/releaser.yml)
[](https://pkg.go.dev/github.com/vultr/govultr/v3)
[](https://github.com/vultr/govultr/actions/workflows/coverage.yml)
[](https://goreportcard.com/report/github.com/vultr/govultr)
The official Vultr Go client - GoVultr allows you to interact with the Vultr V2 API.
## Installation
```sh
go get -u github.com/vultr/govultr/v3
```
## Usage
Vultr uses a personal access token (PAT) 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.
To instantiate a GoVultr client, invoke `NewClient()`. Most operations require
that you pass a PAT to an `oauth2` library to create the `*http.Client`, which
configures the `Authorization` header with your PAT as the `bearer api-key`. If
a PAT is not provided, public operations like listing plans or applications
will still work.
The client has three optional parameters:
- BaseUrl: Change the Vultr default base URL
- UserAgent: Change the Vultr default UserAgent
- RateLimit: Set a delay between calls. Vultr limits the rate of back-to-back calls. Use this parameter to avoid rate-limit errors.
### Example Client Setup
```go
package main
import (
"context"
"os"
"github.com/vultr/govultr/v3"
"golang.org/x/oauth2"
)
func main() {
apiKey := os.Getenv("VultrAPIKey")
config := &oauth2.Config{}
ctx := context.Background()
ts := config.TokenSource(ctx, &oauth2.Token{AccessToken: apiKey})
vultrClient := govultr.NewClient(oauth2.NewClient(ctx, ts))
// Optional changes
_ = vultrClient.SetBaseURL("https://api.vultr.com")
vultrClient.SetUserAgent("mycool-app")
vultrClient.SetRateLimit(500)
}
```
Passing `nil` to `NewClient` will work for routes that do not require
authentication.
```go
...
vultrClient := govultr.NewClient(nil)
ctx := context.Background()
plans, _, _, err := vultrClient.Plan.List(ctx, "", nil)
...
```
### Example Usage
Create a VPS
```go
instanceOptions := &govultr.InstanceCreateReq{
Label: "awesome-go-app",
Hostname: "awesome-go.com",
Backups: "enabled",
EnableIPv6: BoolToBoolPtr(false),
OsID: 362,
Plan: "vc2-1c-2gb",
Region: "ewr",
}
res, err := vultrClient.Instance.Create(context.Background(), instanceOptions)
if err != nil {
fmt.Println(err)
}
```
## Pagination
GoVultr 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.
```go
// Meta represents the available pagination information
type Meta struct {
Total int `json:"total"`
Links *Links
}
// Links represent the next/previous cursor in your pagination calls
type Links struct {
Next string `json:"next"`
Prev string `json:"prev"`
}
```
Pass 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.
This example demonstrates how to retrieve all of your instances, with one
instance per page.
```go
listOptions := &govultr.ListOptions{PerPage: 1}
for {
i, meta, err := client.Instance.List(ctx, listOptions)
if err != nil {
return nil, err
}
for _, v := range i {
fmt.Println(v)
}
if meta.Links.Next == "" {
break
} else {
listOptions.Cursor = meta.Links.Next
continue
}
}
```
## Versioning
This project follows [SemVer](http://semver.org/) for versioning. For the
versions available, see the [tags on this
repository](https://github.com/vultr/govultr/tags).
## Documentation
See our documentation for [detailed information about API v2](https://www.vultr.com/api/).
See our [GoDoc](https://pkg.go.dev/github.com/vultr/govultr/v3) documentation for more details about this client's functionality.
## Contributing
Feel free to send pull requests our way! Please see the [contributing guidelines](CONTRIBUTING.md).
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE) file for details.