katapult

README

go-katapult

Go client library for Katapult.

---

WARNING: Work in progress; features are missing, there will be breaking changes.

---

Documentation:

• API Documentation
• Katapult Documentation

Experimental "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 := client.GetDataCenterDefaultNetworkWithResponse(ctx,
	&katapult.GetDataCenterDefaultNetworkParams{
		DataCenterPermalink: "perma-link",
	},
)

Documentation

Index

• Constants
• Variables
• type Client
  • func New(opts ...Option) (*Client, error)
  • func (c *Client) Do(ctx context.Context, request *Request, v interface{}) (*Response, error)
• type CommonError
  • func NewCommonError(parent error, code, description string) CommonError
  • func (s *CommonError) BaseError() string
  • func (s *CommonError) Error() string
  • func (s *CommonError) Is(target error) bool
  • func (s *CommonError) Unwrap() error
• type HTTPClient
• type Option
  • func WithAPIKey(key string) Option
  • func WithBaseURL(u *url.URL) Option
  • func WithHTTPClient(hc HTTPClient) Option
  • func WithUserAgent(ua string) Option
• type Pagination
• type Request
  • func NewRequest(method string, u *url.URL, body interface{}, opts ...RequestOption) *Request
• type RequestOption
  • func RequestSetHeader(key, value string) RequestOption
• type Response
  • func NewResponse(r *http.Response) *Response
• type ResponseError
  • func NewResponseError(httpStatus int, code string, description string, rawDetail json.RawMessage) *ResponseError
  • func (s *ResponseError) Error() string
  • func (s *ResponseError) Is(target error) bool
  • func (s *ResponseError) Unwrap() error
• type ScopeNotGrantedError
  • func NewScopeNotGrantedError(theError *ResponseError) *ScopeNotGrantedError
  • func (s *ScopeNotGrantedError) Error() string
• type ScopeNotGrantedErrorDetail

Constants

const (
	DefaultUserAgent = "go-katapult"
	DefaultTimeout   = time.Second * 60
)

Variables

var (
	// Err is the top-most parent of any error returned by katapult.
	Err = errors.New("katapult")

	// ErrRequest is returned when there's an issue with building the request.
	ErrRequest = fmt.Errorf("%w: request", Err)

	// ErrConfig is returned when there's a configuration related issue.
	ErrConfig = fmt.Errorf("%w: config", Err)

	// ErrResponse is the parent of all response API related errors.
	ErrResponse = fmt.Errorf("%w", Err)

	// ErrResourceNotFound is a parent error of all resource-specific not found
	// errors.
	ErrResourceNotFound = fmt.Errorf("%w", ErrNotFound)

	// ErrRouteNotFound indicates the API endpoint called does not exist. This
	// generally will mean go-katapult is very old and needs to be updated.
	ErrRouteNotFound = fmt.Errorf("%w: route_not_found", ErrResponse)

	// ErrUnexpectedResponse is returned if the response body did not contain
	// expected data.
	ErrUnexpectedResponse = fmt.Errorf("%w: unexpected_response", ErrResponse)

	// ErrUnknown is returned if the response error could not be understood.
	ErrUnknown = fmt.Errorf("%w: unknown_error", ErrResponse)
)

var (
	ErrBadRequest          = fmt.Errorf("%w: bad_request", ErrResponse)
	ErrUnauthorized        = fmt.Errorf("%w: unauthorized", ErrResponse)
	ErrForbidden           = fmt.Errorf("%w", ErrUnauthorized)
	ErrNotFound            = fmt.Errorf("%w: not_found", ErrResponse)
	ErrNotAcceptable       = fmt.Errorf("%w: not_acceptable", ErrResponse)
	ErrConflict            = fmt.Errorf("%w: conflict", ErrResponse)
	ErrUnprocessableEntity = fmt.Errorf("%w: unprocessable_entity", ErrResponse)
	ErrTooManyRequests     = fmt.Errorf("%w: too_many_requests", ErrResponse)

	ErrInternalServerError = fmt.Errorf(
		"%w: internal_server_error", ErrResponse,
	)
	ErrBadGateway         = fmt.Errorf("%w: bad_gateway", ErrResponse)
	ErrServiceUnavailable = fmt.Errorf("%w: service_unavailable", ErrResponse)
	ErrGatewayTimeout     = fmt.Errorf("%w: gateway_timeout", ErrResponse)
)

HTTP status-based errors. These may be returned directly, or act as the parent error for a more specific error.

var DefaultURL = &url.URL{Scheme: "https", Host: "api.katapult.io"}

var ErrScopeNotGranted = fmt.Errorf("%w: scope_not_granted", ErrForbidden)

Types

type Client

type Client struct {
	HTTPClient HTTPClient

	APIKey    string
	UserAgent string
	BaseURL   *url.URL
}

func New

func New(opts ...Option) (*Client, error)

func (*Client) Do

func (c *Client) Do(
	ctx context.Context,
	request *Request,
	v interface{},
) (*Response, error)

type CommonError

type CommonError struct {
	Code        string `json:"code,omitempty"`
	Description string `json:"description,omitempty"`
	// contains filtered or unexported fields
}

CommonError handles common logic shared between all API-based error types.

func NewCommonError

func NewCommonError(parent error, code, description string) CommonError

func (*CommonError) BaseError

func (s *CommonError) BaseError() string

func (*CommonError) Error

func (s *CommonError) Error() string

func (*CommonError) Is

func (s *CommonError) Is(target error) bool

func (*CommonError) Unwrap

func (s *CommonError) Unwrap() error

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type Option

type Option func(c *Client) error

func WithAPIKey

func WithAPIKey(key string) Option

func WithBaseURL

func WithBaseURL(u *url.URL) Option

func WithHTTPClient

func WithHTTPClient(hc HTTPClient) Option

func WithUserAgent

func WithUserAgent(ua string) Option

type Pagination

type Pagination struct {
	CurrentPage int  `json:"current_page,omitempty"`
	TotalPages  int  `json:"total_pages,omitempty"`
	Total       int  `json:"total,omitempty"`
	PerPage     int  `json:"per_page,omitempty"`
	LargeSet    bool `json:"large_set,omitempty"`
}

type Request

type Request struct {
	// Method is the HTTP method to perform when making the request.
	Method string

	// URL is the request URL to perform against Katapult's API. Generally the
	// only fields you need to set are Path and RawQuery, as it will be merged
	// with the Client's BaseURL value through its ResolveReference() method.
	URL *url.URL

	// NoAuth instructs Client not to send Authorization header containing the
	// APIKey. This is useful for public endpoints which do not require/use
	// authentication.
	NoAuth bool

	// Header holds request-specific HTTP headers. Client.Do() will set a number
	// of essential headers itself which cannot be customized through
	// Request.Headers.
	Header http.Header

	// ContentType allows sending a custom request body of any mimetype. If set
	// Body must be a io.Reader. If not set Body must be a object which can be
	// serialized with json.Marshal(). Content-Type header is only sent when
	// Body is not nil.
	ContentType string

	// Body can be any object which can be marshaled to JSON through
	// json.Marshal() when ContentType is not set. If ContentType is set, Body
	// must be a io.Reader, or nil.
	//
	// No validation is performed between Method and Body, making it possible to
	// send a body with a method that does not allow it.
	Body interface{}
}

Request represents a HTTP request to the Katapult API, it is essentially similar to http.Request, but stripped down to the bare essentials, with some Katapult-specific attributes added.

func NewRequest

func NewRequest(
	method string,
	u *url.URL,
	body interface{},
	opts ...RequestOption,
) *Request

type RequestOption

type RequestOption = func(r *Request)

func RequestSetHeader

func RequestSetHeader(key, value string) RequestOption

RequestSetHeader sets a header on the outgoing request. This replaces any headers that are currently specified with that key.

type Response

type Response struct {
	*http.Response

	Pagination *Pagination
	Error      *ResponseError
}

func NewResponse

func NewResponse(r *http.Response) *Response

type ResponseError

type ResponseError struct {
	Code        string          `json:"code,omitempty"`
	Description string          `json:"description,omitempty"`
	Detail      json.RawMessage `json:"detail,omitempty"`
	// contains filtered or unexported fields
}

func NewResponseError

func NewResponseError(
	httpStatus int,
	code string,
	description string,
	rawDetail json.RawMessage,
) *ResponseError

func (*ResponseError) Error

func (s *ResponseError) Error() string

func (*ResponseError) Is

func (s *ResponseError) Is(target error) bool

func (*ResponseError) Unwrap

func (s *ResponseError) Unwrap() error

type ScopeNotGrantedError

type ScopeNotGrantedError struct {
	CommonError
	Detail *ScopeNotGrantedErrorDetail `json:"detail,omitempty"`
}

ScopeNotGrantedError: The scope required for this endpoint has not been granted to the authenticating identity.

func NewScopeNotGrantedError

func NewScopeNotGrantedError(theError *ResponseError) *ScopeNotGrantedError

func (*ScopeNotGrantedError) Error

func (s *ScopeNotGrantedError) Error() string

type ScopeNotGrantedErrorDetail

type ScopeNotGrantedErrorDetail struct {
	Scopes []string `json:"scopes,omitempty"`
}