oxide.go

IMPORTANT: This SDK is under heavy development and will have constant breaking changes.

The Go API client for administrating an Oxide rack.

To contribute to this repository make sure you read the contributing documentation.

Getting started

Make sure you have installed Go 1.21.x or above.

Installation

Use go get inside your module dependencies directory

go get github.com/oxidecomputer/oxide.go@latest

Usage example

package main

import (
	"fmt"

	"github.com/oxidecomputer/oxide.go/oxide"
)

func main() {
	client, err := oxide.NewClient(
		oxide.WithHost("https://api.oxide.computer"),
		oxide.WithToken("oxide-abc123"),
	)
	if err != nil {
		panic(err)
	}

	ctx := context.Background()
	params := oxide.ProjectCreateParams{
		Body: &oxide.ProjectCreate{
			Description: "A sample project",
			Name:        oxide.Name("my-project"),
		},
	}

	resp, err := client.ProjectCreate(ctx, params)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%+v\n", resp)
}

Authentication

The client supports several authentication methods.

1. Explicit options: Use WithHost and WithToken:

   client, err := oxide.NewClient(
       oxide.WithHost("https://api.oxide.computer"),
       oxide.WithToken("oxide-abc123"),
   )

2. Environment variables: Set OXIDE_HOST and OXIDE_TOKEN:

   export OXIDE_HOST="https://api.oxide.computer"
   export OXIDE_TOKEN="oxide-abc123"

   Then create the client with no options:

   client, err := oxide.NewClient()

3. Oxide profile: Use a profile from the Oxide config file:

   client, err := oxide.NewClient(oxide.WithProfile("my-profile"))

   Or set the OXIDE_PROFILE environment variable:

   export OXIDE_PROFILE="my-profile"

4. Default profile: Use the default profile from the Oxide config file:

   client, err := oxide.NewClient(oxide.WithDefaultProfile())

When using profiles, the client reads from the Oxide credentials file located at $HOME/.config/oxide/credentials.toml, or a custom directory via WithConfigDir.

Options override environment variables. Configuring both profile and host/token options is disallowed and will return an error, as will configuring both WithProfile and WithDefaultProfile.