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",
},
)
Set 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.
This includes the standard http.Response as well as 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 numerous pointers for its parameters and primarily returns pointers in its response objects. If the value is a pointer it most likely is marked as optional in the API.
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