435c0d9fc8
This PR switches the Nomad repository from using govendor to Go modules for managing dependencies. Aspects of the Nomad workflow remain pretty much the same. The usual Makefile targets should continue to work as they always did. The API submodule simply defers to the parent Nomad version on the repository, keeping the semantics of API versioning that currently exists.
179 lines
5 KiB
Markdown
179 lines
5 KiB
Markdown
# linodego
|
|
|
|
[](https://travis-ci.org/linode/linodego)
|
|
[](https://godoc.org/github.com/linode/linodego)
|
|
[](https://goreportcard.com/report/github.com/linode/linodego)
|
|
[](https://codecov.io/gh/linode/linodego)
|
|
|
|
Go client for [Linode REST v4 API](https://developers.linode.com/api/v4)
|
|
|
|
## Installation
|
|
|
|
```sh
|
|
go get -u github.com/linode/linodego
|
|
```
|
|
|
|
## API Support
|
|
|
|
Check [API_SUPPORT.md](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](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://developers.linode.com/api/v4).
|
|
|
|
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"
|
|
|
|
"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
|
|
|
|
```go
|
|
kernels, err := linodego.ListKernels(context.Background(), nil)
|
|
// len(kernels) == 218
|
|
```
|
|
|
|
Or, use a page value of "0":
|
|
|
|
```go
|
|
opts := NewListOptions(0,"")
|
|
kernels, err := linodego.ListKernels(context.Background(), opts)
|
|
// len(kernels) == 218
|
|
```
|
|
|
|
#### Single Page
|
|
|
|
```go
|
|
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.
|
|
|
|
```go
|
|
// opts.Results == 218
|
|
```
|
|
|
|
#### Filtering
|
|
|
|
```go
|
|
opts := ListOptions{Filter: "{\"mine\":true}"}
|
|
// or opts := NewListOptions(0, "{\"mine\":true}")
|
|
stackscripts, err := linodego.ListStackscripts(context.Background(), opts)
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
#### Getting Single Entities
|
|
|
|
```go
|
|
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.
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
// 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](https://gophers.slack.com/messages/CAG93EB2S) on the [gophers slack](https://gophers.slack.com)
|
|
|
|
## License
|
|
|
|
[MIT License](LICENSE)
|