Skip to content

optik-aper/govultr

This branch is 1 commit ahead of, 10 commits behind vultr/govultr:master.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

897dc76 · Oct 30, 2024
Oct 22, 2024
Mar 20, 2023
Oct 22, 2024
Dec 8, 2021
Oct 30, 2024
Jul 1, 2019
May 2, 2019
Dec 11, 2023
Mar 15, 2023
Jul 24, 2023
Jul 24, 2023
Jul 24, 2023
Jul 24, 2023
Jul 24, 2023
Oct 10, 2024
Aug 10, 2023
Jul 24, 2023
Jul 24, 2023
Jul 24, 2023
Mar 15, 2023
Oct 8, 2024
Oct 9, 2024
Nov 17, 2023
Nov 17, 2023
Oct 30, 2024
Oct 17, 2024
Jul 24, 2023
Mar 15, 2023
Jul 24, 2023
Jan 31, 2023
Jul 24, 2023
Mar 15, 2023
Oct 1, 2024
Oct 1, 2024
Oct 9, 2024
Oct 9, 2024
Oct 30, 2024
Jul 24, 2023
Jun 5, 2024
Jun 5, 2024
Oct 1, 2024
Sep 19, 2024
Nov 19, 2020
Jul 24, 2023
Mar 15, 2023
Mar 7, 2024
Feb 20, 2024
Jan 20, 2022
Oct 1, 2024
Sep 19, 2024
Dec 14, 2023
Dec 14, 2023
Feb 28, 2024
Jun 29, 2020
Nov 10, 2023
Mar 15, 2023
Jul 24, 2023
Mar 15, 2023
Jul 24, 2023
Mar 15, 2023
Jul 24, 2023
Mar 15, 2023
Jul 24, 2023
Mar 15, 2023
Jul 24, 2023
Mar 15, 2023
Jul 24, 2023
Mar 15, 2023
Feb 28, 2024
Mar 15, 2023
Oct 9, 2024
Oct 9, 2024
Jul 24, 2023
Mar 15, 2023
Sep 19, 2024
Aug 18, 2023
Aug 18, 2023
Mar 15, 2023

Repository files navigation

GoVultr

Automatic Releaser PkgGoDev Unit/Coverage Tests Go Report Card

The official Vultr Go client - GoVultr allows you to interact with the Vultr V2 API.

Installation

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

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.

  ... 

  vultrClient := govultr.NewClient(nil)
  ctx := context.Background()
  plans, _, _, err := vultrClient.Plan.List(ctx, "", nil)

  ...

Example Usage

Create a VPS

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.

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

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 for versioning. For the versions available, see the tags on this repository.

Documentation

See our documentation for detailed information about API v2.

See our GoDoc documentation for more details about this client's functionality.

Contributing

Feel free to send pull requests our way! Please see the contributing guidelines.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

About

Vultr Go API client

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Go 100.0%