• Stars
    star
    138
  • Rank 264,508 (Top 6 %)
  • Language
    Go
  • License
    MIT License
  • Created about 7 years ago
  • Updated 30 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Go client for Linode REST v4 API

linodego

Tests Release GoDoc Go Report Card

Go client for Linode REST v4 API

Installation

go get -u github.com/linode/linodego

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 := linodego.NewListOptions(0,"")
kernels, err := linodego.ListKernels(context.Background(), opts)
// len(kernels) == 218

Single Page

opts := linodego.NewListOptions(2,"")
// or opts := linodego.ListOptions{PageOptions: &linodego.PageOptions{Page: 2}, PageSize: 500}
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

f := linodego.Filter{}
f.AddField(linodego.Eq, "mine", true)
fStr, err := f.MarshalJSON()
if err != nil {
    log.Fatal(err)
}
opts := linodego.NewListOptions(0, string(fStr))
stackscripts, err := linodego.ListStackscripts(context.Background(), opts)

Error Handling

Getting Single Entities

linode, err := linodego.GetInstance(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.ListInstances(context.Background(), linodego.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.ListInstances(context.Background(), linodego.NewListOptions(9999, ""))
// linodes == []
// err = nil

Response Caching

By default, certain endpoints with static responses will be cached into memory. Endpoints with cached responses are identified in their accompanying documentation.

The default cache entry expiry time is 15 minutes. Certain endpoints may override this value to allow for more frequent refreshes (e.g. client.GetRegion(...)). The global cache expiry time can be customized using the client.SetGlobalCacheExpiration(...) method.

Response caching can be globally disabled or enabled for a client using the client.UseCache(...) method.

The global cache can be cleared and refreshed using the client.InvalidateCache() method.

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 testunit to run the unit tests.

Run make testint to run the integration tests. The integration tests use fixtures.

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

More Repositories

1

apl-core

Application Platform for Linode Kubernetes Engine (or any other K8s)
Smarty
2,212
star
2

docs

Linode guides and tutorials.
Python
1,380
star
3

manager

Akamai's Cloud Manager is an open-source, single-page application designed as the primary frontend interface for interacting with the Linode API. It is entrusted by hundreds of thousands of customers with the management of their Linode services.
TypeScript
689
star
4

cli

This is the DEPRECATED Linode CLI. Use https://github.com/linode/linode-cli
Perl
466
star
5

linode-cli

The official Linode command line interface.
Python
376
star
6

longview

Linode Longview Agent
Perl
334
star
7

terraform-provider-linode

Terraform Linode provider
Go
203
star
8

linode_api4-python

Official Python bindings for the Linode API
Python
136
star
9

linode-cloud-controller-manager

Kubernetes Cloud Controller Manager for Linode
Go
83
star
10

terraform-linode-k8s

Kubernetes installer for Linode
HCL
67
star
11

linode-blockstorage-csi-driver

Container Storage Interface (CSI) Driver for Linode Block Storage
Go
65
star
12

ansible_linode

Linode Ansible Collection
Python
57
star
13

Marketplace-Apps

The Linode Marketplace is designed to make it easier for developers and companies to share One-Click Apps with the Linode community.
Shell
53
star
14

docker-volume-linode

Docker Volume driver for Linode Block Storage
Go
46
star
15

docker-machine-driver-linode

Linode Driver Plugin for Docker Machine using Linode APIv4
Go
44
star
16

cluster-api-provider-linode

A Cluster API implementation to create Kubernetes clusters for Linode (CAPL)
Go
26
star
17

beginners-guide-to-devops-tools

SCSS
26
star
18

linode-api-docs

Source for the Linode API v4 Docs
Python
23
star
19

packer-builder-linode

Packer Builder plugin for Linode Images
Go
21
star
20

apl-tasks

Tasks needed by APL to glue all the pieces together
TypeScript
20
star
21

provider-ceph

Provider Ceph is a Crossplane provider capable of managing S3 Buckets on one or more Ceph clusters.
Go
18
star
22

homebrew-cli

Homebrew formula for Linode CLI
Ruby
14
star
23

provider-linode

Provider Linode is a Crossplane provider for managing Linode Akamai Cloud Computing resources.
Go
12
star
24

packer-plugin-linode

Packer plugin for Linode Builder
Go
10
star
25

k8s-node-decorator

Add labels and annotations to your kubernetes nodes with this in cluster decorator that reads data from the metadata for the underlying linodes
Go
10
star
26

apl-clients

Factory to build and publish open API clients used in the apl-tasks repo
Shell
10
star
27

kontainer-engine-driver-lke

Kontainer Engine Driver for Rancher Cluster Driver
Go
8
star
28

developers

developers-linode-com
JavaScript
8
star
29

action-linode-cli

A GitHub Action for installing the Linode CLI
8
star
30

lelastic

elastic IP client
Go
7
star
31

linode-doc-template

Template for creating bounty docs for Linode.
6
star
32

rancher-ui-driver-linode

UI for Linode options when used as a Rancher Node Template
JavaScript
6
star
33

linode-react-components

React Components consumed by linode/manager and linode/linode-api-docs
JavaScript
6
star
34

linode-k8s-e2e-tests

A collection of end-to-end test for Kubernetes running on Linode
Go
6
star
35

velero-plugin

Verlero plugin that clones Linode CSI volumes for archival
Go
5
star
36

capi-bootstrap

Cluster API self-managed cluster bootstrapping
Go
4
star
37

linode-cosi-driver

A Kubernetes Container Object Storage Interface (COSI) Driver for Linode
Go
4
star
38

agreements

Linode's Legal Agreements
4
star
39

go-metadata

A Go package for interacting with the Linode Metadata Service.
Go
4
star
40

apl-docs

App Platform for LKE documentation website - https://apl-docs.net
JavaScript
4
star
41

linode-hugo-theme

JavaScript
4
star
42

manager-design

Design repository for the Linode manager
4
star
43

ui-cluster-driver-lke

UI for Linode options when used as a Rancher Cluster Driver
JavaScript
3
star
44

terraform-linode-dcos

[WORK-IN-PROGRESS] DC/OS Provisioning Terraform module for Linode
HCL
3
star
45

design-language-system

A repository of our foundational design tokens in various formats help build a cohesive and consistent visual language across digital platforms. Includes color palettes, typography, spacing, layout rules, and more. Provides a pre-built set of tokens for designers and developers to easily implement in their projects, promoting brand identity
TypeScript
3
star
46

apl-charts

App Platform for LKE - Catalog Helm charts
Smarty
3
star
47

ansible-specdoc

A utility for dynamically generating Ansible Collection documentation.
Python
2
star
48

py-metadata

A Python package for interacting with the Linode Metadata Service.
Python
2
star
49

styles

Linode stylesheets
CSS
2
star
50

lke-sintel-demo

Three manifest Nginx Ingress, Cert Manager, and External DNS demo on Linode Kubernetes Engine
HTML
2
star
51

ndproxy

Go
2
star
52

dhcpd-unnumbered

Go
2
star
53

arpproxy

Go
2
star
54

docs-cloud-projects

Jinja
1
star
55

docs-scripts

Python
1
star
56

ansible-specdoc-example

An example Ansible Collection using ansible-specdoc.
Python
1
star
57

splunk-addon-linode

Linode Splunk Integration
Python
1
star
58

rad-unnumbered

Go
1
star
59

cloud-firewall-controller

Go
1
star