1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
|
# linodego

[](https://github.com/linode/linodego/releases/latest)
[](https://godoc.org/github.com/linode/linodego)
[](https://goreportcard.com/report/github.com/linode/linodego)
Go client for [Linode REST v4 API](https://techdocs.akamai.com/linode-api/reference/api)
## Installation
```sh
go get -u github.com/linode/linodego
```
## Documentation
See [godoc](https://godoc.org/github.com/linode/linodego) for a complete reference.
The API generally follows the naming patterns prescribed in the [OpenAPIv3 document for Linode APIv4](https://techdocs.akamai.com/linode-api/reference/api).
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
```go
package main
import (
"context"
"fmt"
"log"
"net/http"
"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 := 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
```go
kernels, err := linodego.ListKernels(context.Background(), nil)
// len(kernels) == 218
```
Or, use a page value of "0":
```go
opts := linodego.NewListOptions(0,"")
kernels, err := linodego.ListKernels(context.Background(), opts)
// len(kernels) == 218
```
#### Single Page
```go
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.
```go
// opts.Results == 218
```
> **_NOTES:_**
> - 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.
#### Filtering
```go
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
```go
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.
```go
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:
```go
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](https://pkg.go.dev/github.com/linode/linodego?utm_source=godoc).
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:
```go
// err.Error() == "[400] [field1] foo problem; [field2] bar problem; [field3] baz problem"
```
## Tests
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`.
## Discussion / Help
Join us at [#linodego](https://gophers.slack.com/messages/CAG93EB2S) on the [gophers slack](https://gophers.slack.com)
## License
[MIT License](LICENSE)
|