Go Client

We maintain a client for go here

next Client

A more feature complete client is being generated in the next package. The aim for this client is to be generated from an openapi spec and should offer access to everything that is documented / exposed in our API documentation.

Usage Guidance

Each endpoint has multiple functions for calling it. Typically FunctionName and FunctionNameWithResponse are provided.

It is recommended to use the FunctionNameWithResponse functions as they return a response object that contains the response data and the HTTP response object.

The FunctionName functions are provided for convenience and return only the response data.

Example

res, err := katapult.GetDataCenterDefaultNetworkWithResponse(ctx,
	&core.GetDataCenterDefaultNetworkParams{
		DataCenterPermalink: "perma-link",
	},
)

Setting up the client

package main 

import "github.com/krystal/go-katapult/next/core"

func main() {
	katapult, err := core.NewClientWithResponses(
		d.katapultURL,
		d.katapultToken,
	)

	if err != nil {
		log.Fatalf("failed to create katapult client: %v", err)
	}

	// Use the client - `katapult`.
}

Client Response Object

The response object contains a lot of useful information about the response from the API. Including the standard http.Response but also several other nested structs that contain possible response data. Essentially each Response Object is custom to the endpoint and will contain all possible response structures.

For example the GetDataCenterDefaultNetworkWithResponse function returns a GetDataCenterDefaultNetworkResponse struct. This struct looks like this.

type GetDataCenterDefaultNetworkResponse struct {
	Body         []byte
	HTTPResponse *http.Response
	JSON200      *struct {
		// Network The details for the requested network
		Network GetDataCenterDefaultNetwork200ResponseNetwork `json:"network"`
	}
	JSON400 *APIAuthenticator400Response
	JSON403 *APIAuthenticator403Response
	JSON404 *DataCenterNotFoundResponse
	JSON429 *APIAuthenticator429Response
	JSON503 *APIAuthenticator503Response
}

This pattern applies to all response objects. and you should reasonably be able to always extract your successful response data from the JSON2xx field after checking if the returned error is nil.

res, err := client.GetDataCenterDefaultNetworkWithResponse(ctx,
	&katapult.GetDataCenterDefaultNetworkParams{
		DataCenterPermalink: "perma-link",
	},
)

if err != nil {
	// handle error
}

Network := res.JSON200.Network

// do something with Network

Errors returned by the client

The client has a few custom errors that are returned when the API returns an error. Specifically these are returned when the API returns a 404 or the API does not respond with a 2xx status code.

var (
    ErrRequestFailed = errors.New("request was not successful")
    ErrNotFound = errors.New("resource not found")
)

Whilst it returns these errors it will still also return the response object so you can inspect the response body, the response status etc.

As an example

res, err := client.GetDataCenterDefaultNetworkWithResponse(ctx,
	&katapult.GetDataCenterDefaultNetworkParams{
		DataCenterPermalink: "perma-link",
	},
)
if err != nil && errors.Is(err, core.ErrNotFound) {
	// handle not found error
	fmt.Println(res.JSON404)
}

A note about pointers

The client requires alot of pointers for it's parameters, it will also return mostly pointers in the response objects. The reason for this is that if the value is a pointer it most likely is marked as optional in the API.

warning

Take caution when dereferencing these pointers as they may be nil.

A note about nullable.Nullable

A few fields in response objects are nullable.Nullable which is a generic type which can be used to retrieve an actual value after interrogating whether the value is nil or not.

type Nullable[T any] map[bool]T
Nullable is a generic type, which implements a field that can be one of three states:

- field is not set in the request - field is explicitly set to `null` in the request - field is explicitly set to a valid value in the request

Nullable is intended to be used with JSON marshalling and unmarshalling.

Internal implementation details:

- map[true]T means a value was provided - map[false]T means an explicit null was provided - nil or zero map means the field was not provided

If the field is expected to be optional, add the `omitempty` JSON tags. Do NOT use `*Nullable`!

Adapted from https://github.com/golang/go/issues/64515#issuecomment-1841057182

func (t Nullable[T]) Get() (T, error)
func (t Nullable[T]) IsNull() bool
func (t Nullable[T]) IsSpecified() bool
func (t Nullable[T]) MarshalJSON() ([]byte, error)
func (t Nullable[T]) MustGet() T
func (t *Nullable[T]) Set(value T)
func (t *Nullable[T]) SetNull()
func (t *Nullable[T]) SetUnspecified()
func (t *Nullable[T]) UnmarshalJSON(data []byte) error