Go client for Linode REST v4 API

go get -u github.com/linode/linodego

Check API_SUPPORT.md for current support of the Linode v4 API endpoints.

** Note: This project will change and break until we release a v1.0.0 tagged version. Breaking changes in v0.x.x will be denoted with a minor version bump (v0.2.4 -> v0.3.0) **

See godoc for a complete reference.

The API generally follows the naming patterns prescribed in the OpenAPIv3 document for Linode APIv4.

Deviations in naming have been made to avoid using "Linode" and "Instance" redundantly or inconsistently.

A brief summary of the features offered in this API client are shown here.

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  "github.com/linode/linodego"
  "golang.org/x/oauth2"
)

func main() {
  apiKey, ok := os.LookupEnv("LINODE_TOKEN")
  if !ok {
    log.Fatal("Could not find LINODE_TOKEN, please assert it is set.")
  }
  tokenSource := oauth2.StaticTokenSource(&oauth2.Token{AccessToken: apiKey})

  oauth2Client := &http.Client{
    Transport: &oauth2.Transport{
      Source: tokenSource,
    },
  }

  linodeClient, err := linodego.NewClient(oauth2Client)
  if err != nil {
    log.Fatal(err)
  }
  linodeClient.SetDebug(true)
  res, err := linodeClient.GetInstance(context.Background(), 4090913)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%v", res)
}

kernels, err := linodego.ListKernels(context.Background(), nil)
// len(kernels) == 218

Or, use a page value of "0":

opts := NewListOptions(0,"")
kernels, err := linodego.ListKernels(context.Background(), opts)
// len(kernels) == 218

opts := NewListOptions(2,"")
// or opts := ListOptions{PageOptions: &PageOptions: {Page: 2 }}
kernels, err := linodego.ListKernels(context.Background(), opts)
// len(kernels) == 100

ListOptions are supplied as a pointer because the Pages and Results values are set in the supplied ListOptions.

// opts.Results == 218

opts := ListOptions{Filter: "{\"mine\":true}"}
// or opts := NewListOptions(0, "{\"mine\":true}")
stackscripts, err := linodego.ListStackscripts(context.Background(), opts)

linode, err := linodego.GetLinode(context.Background(), 555) // any Linode ID that does not exist or is not yours
// linode == nil: true
// err.Error() == "[404] Not Found"
// err.Code == "404"
// err.Message == "Not Found"

For lists, the list is still returned as [], but err works the same way as on the Get request.

linodes, err := linodego.ListLinodes(context.Background(), NewListOptions(0, "{\"foo\":bar}"))
// linodes == []
// err.Error() == "[400] [X-Filter] Cannot filter on foo"

Otherwise sane requests beyond the last page do not trigger an error, just an empty result:

linodes, err := linodego.ListLinodes(context.Background(), NewListOptions(9999, ""))
// linodes == []
// err = nil

When performing a POST or PUT request, multiple field related errors will be returned as a single error, currently like:

// err.Error() == "[400] [field1] foo problem; [field2] bar problem; [field3] baz problem"

Run make test to run the unit tests. This is the same as running go test except that make test will execute the tests while playing back API response fixtures that were recorded during a previous development build.

go test can be used without the fixtures, so long as LINODE_TEST_INSTANCE and LINODE_TEST_VOLUME are set to an instance ID and volume ID that exists on your account. The Linode instance must have a backup and a snapshot to match the test expectations. Copy env.sample to .env and configure your persistent test settings, including an API token.

go test -short can be used to run live API tests that do not require an account token.

This will be simplified in future versions.

To update the test fixtures, run make fixtures. This will record the API responses into the fixtures/ directory. Be careful about committing any sensitive account details. An attempt has been made to sanitize IP addresses and dates, but no automated sanitization will be performed against fixtures/*Account*.yaml, for example.

To prevent disrupting unaffected fixtures, target fixture generation like so: make ARGS="-run TestListVolumes" fixtures.

Join us at #linodego on the gophers slack

MIT License