Go client for Linode REST v4 API
go get -u github.com/linode/linodego/v2
See godoc for a complete reference.
For guidance on waiting for asynchronous API operations, see Event and Status Polling.
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" "net/http" "os" "github.com/linode/linodego/v2" "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 := linodego.NewListOptions(0,"") kernels, err := linodego.ListKernels(context.Background(), opts) // len(kernels) == 218
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 == 218NOTES:
- The ListOptions will be mutated by list endpoint functions.
- Instances of ListOptions should NOT be shared across multiple list endpoint functions.
- The resulting number of results and pages can be accessed through the user-supplied ListOptions instance.
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)
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"
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
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.
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-unit to run the unit tests.
Run make test-int 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 TEST_ARGS="-run TestListVolumes" fixtures.
Join us at #linodego on the gophers slack