Go client for Linode REST v4 API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.chglog fix: rename chiefy to linode, thanks @chiefy! Aug 15, 2018
fixtures fix the notifications endpoint, add tests and constants Dec 6, 2018
.gitignore Update codecov.io settings in .travis.yml Jul 22, 2018
.travis.yml
API_SUPPORT.md add support for the top-level profile/ endpoint (#60) Oct 27, 2018
CHANGELOG.md version bump to 0.7.0 Dec 3, 2018
Gopkg.lock Switch go-resty import path to gopkg.in version for future go module … Sep 16, 2018
Gopkg.toml
LICENSE
Makefile
README.md
account.go add missing account fields: address_1, address_2, phone Oct 27, 2018
account_events.go fix json parsing for event time_remaining values Sep 7, 2018
account_events_test.go fix json parsing for event time_remaining values Sep 7, 2018
account_invoices.go
account_notifications.go fix the notifications endpoint, add tests and constants Dec 6, 2018
account_notifications_test.go fix the notifications endpoint, add tests and constants Dec 6, 2018
account_test.go changed to background Jul 20, 2018
account_users.go feature: add support for user account operations Oct 25, 2018
account_users_test.go feature: add support for user account operations Oct 25, 2018
client.go
client_test.go changed poll time to millisecond granularity. default 3s, deduped fix… Sep 19, 2018
domain_records.go feature: add support for user account operations Oct 25, 2018
domain_records_test.go List*: use slice of thing, not slice of pointer Sep 6, 2018
domains.go add support for domain and volume tags Nov 29, 2018
domains_test.go fix various metalinter warnings Aug 27, 2018
env.sample
errors.go Switch go-resty import path to gopkg.in version for future go module … Sep 16, 2018
example_integration_test.go
example_nodebalancers_test.go
example_stackscripts_test.go fix: rename chiefy to linode, thanks @chiefy! Aug 15, 2018
example_test.go test that multipaged results ran fixDates Sep 6, 2018
images.go fix Image date handling Oct 14, 2018
images_test.go fix: rename chiefy to linode, thanks @chiefy! Aug 15, 2018
instance_configs.go root_device has no meaning as "", avoid pointers for omission Sep 9, 2018
instance_disks.go ResizeInstanceDisk does not return Disk, add PasswordResetInstanceDis… Sep 19, 2018
instance_ips.go add missing function and type comments Aug 26, 2018
instance_snapshots.go
instance_snapshots_test.go use setup functions in tests to avoid magic number requirements durin… Sep 9, 2018
instance_volumes.go
instances.go
instances_test.go fix gometalinter violations Sep 20, 2018
kernels.go
longview.go apply fixDates in-place on List results Sep 6, 2018
longview_subscriptions.go apply fixDates in-place on List results Sep 6, 2018
managed.go
network_ips.go add support for UpdateIPAddress (RDNS) Dec 3, 2018
network_ips_test.go
network_pools.go
network_ranges.go
nodebalancer.go
nodebalancer_config_nodes.go apply fixDates in-place on List results Sep 6, 2018
nodebalancer_config_nodes_test.go fixes and tests for RebuildNodeBalancerConfig Sep 8, 2018
nodebalancer_configs.go add support for the top-level profile/ endpoint (#60) Oct 27, 2018
nodebalancer_configs_test.go fix redundant or in nodebalancer configs test Aug 27, 2018
nodebalancers_test.go fix various metalinter warnings Aug 27, 2018
pagination.go
profile.go
profile_sshkeys.go root_device has no meaning as "", avoid pointers for omission Sep 9, 2018
profile_sshkeys_test.go
profile_test.go add support for the top-level profile/ endpoint (#60) Oct 27, 2018
profile_tokens.go
profile_tokens_test.go add more profile/token tests Oct 22, 2018
regions.go apply fixDates in-place on List results Sep 6, 2018
regions_test.go changed to background Jul 20, 2018
resources.go fix the notifications endpoint, add tests and constants Dec 6, 2018
resources_test.go fix json parsing for event time_remaining values Sep 7, 2018
snapshots_test.go use sed to replace lingering golinode references May 23, 2018
stackscripts.go apply fixDates in-place on List results Sep 6, 2018
stackscripts_test.go fix: rename chiefy to linode, thanks @chiefy! Aug 15, 2018
support.go
tags.go add support for nodebalancer in TaggedObjects, TagCreateOptions, Sort… Dec 3, 2018
tags_test.go tags can be added immediately to Linode Instances Oct 5, 2018
template.go add more profile/token tests Oct 22, 2018
template_test.go
types.go
types_test.go fix: rename chiefy to linode, thanks @chiefy! Aug 15, 2018
util.go use sed to replace lingering golinode references May 23, 2018
volumes.go
volumes_test.go use setup functions in tests to avoid magic number requirements durin… Sep 9, 2018
waitfor.go

README.md

linodego

Build Status GoDoc Go Report Card codecov

Go client for Linode REST v4 API

Installation

go get -u github.com/linode/linodego

API Support

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

Documentation

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.

Examples

General Usage

package main

import (
	"context"
	"fmt"

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

	"log"
	"net/http"
	"os"
)

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 := linodego.NewClient(oauth2Client)
  linodeClient.SetDebug(true)
  
  res, err := linodeClient.GetInstance(context.Background(), 4090913)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%v", res)
}

Pagination

Auto-Pagination Requests

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

Single Page

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

Filtering

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

Error Handling

Getting Single Entities

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"

Lists

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

Writes

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"

Tests

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

Discussion / Help

Join us at #linodego on the gophers slack

License

MIT License