Documentation
¶
Overview ¶
Package client provides an HTTP client for communicating with the Arcane API.
The client handles authentication, request construction, and response parsing for all API calls. It supports JSON request/response bodies as well as raw multipart uploads.
Creating a Client ¶
The recommended way to create a client is from the CLI configuration:
c, err := client.NewFromConfig()
if err != nil {
return err
}
Making Requests ¶
The client provides convenience methods for common HTTP methods:
resp, err := c.Get(ctx, "/api/images") resp, err := c.Post(ctx, "/api/images/pull", body) resp, err := c.Delete(ctx, "/api/images/abc123")
Index ¶
- type APIResponse
- type Client
- func (c *Client) Delete(ctx context.Context, path string) (*http.Response, error)
- func (c *Client) EnvID() string
- func (c *Client) EnvPath(path string) string
- func (c *Client) Get(ctx context.Context, path string) (*http.Response, error)
- func (c *Client) Post(ctx context.Context, path string, body any) (*http.Response, error)
- func (c *Client) Put(ctx context.Context, path string, body any) (*http.Response, error)
- func (c *Client) Request(ctx context.Context, method, path string, body any) (*http.Response, error)
- func (c *Client) RequestRaw(ctx context.Context, method, path string, body io.Reader, ...) (*http.Response, error)
- func (c *Client) SetEnvironment(envID string)
- func (c *Client) SetTimeout(timeout time.Duration)
- func (c *Client) TestConnection(ctx context.Context) error
- type PaginatedResponse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIResponse ¶
type APIResponse[T any] struct { Success bool `json:"success"` Data T `json:"data"` Error string `json:"error,omitempty"` }
APIResponse wraps the standard Arcane API response format. All API responses include a Success field indicating whether the request succeeded, a Data field containing the response payload, and an optional Error field with error details on failure.
func DecodeResponse ¶
func DecodeResponse[T any](resp *http.Response) (*APIResponse[T], error)
DecodeResponse decodes an API response into the given type. It reads the response body, unmarshals it as JSON, and returns the typed result. If the response indicates failure (Success=false) with a 4xx/5xx status code, an error is returned with the error message from the API. Note: This function closes the response body.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is an HTTP client for the Arcane API. It handles authentication via API tokens and provides methods for making HTTP requests to various API endpoints. The client automatically includes authentication headers and handles JSON serialization.
func New ¶
New creates a new API client from the provided configuration. It validates the configuration and returns an error if required fields (ServerURL, APIKey) are missing. The client is initialized with a default 30-second timeout and the configured environment ID.
func NewFromConfig ¶
NewFromConfig loads the CLI configuration from disk and creates a new client. This is the recommended way to create a client in CLI commands. It returns an error if the configuration cannot be loaded or is invalid.
func NewFromConfigUnauthenticated ¶
NewFromConfigUnauthenticated loads config and returns an unauthenticated client.
func NewUnauthenticated ¶
NewUnauthenticated creates a client that can call unauthenticated endpoints (e.g. /api/auth/login). It only validates that server_url is configured.
func (*Client) Delete ¶
Delete makes a DELETE request to the specified path. It is a convenience wrapper around Request for removing resources.
func (*Client) EnvID ¶
EnvID returns the current environment ID configured for this client. The environment ID is used to scope API requests to a specific environment.
func (*Client) EnvPath ¶
EnvPath returns a path prefixed with the environment. It constructs an environment-scoped API path in the format: /api/environments/{envID}{path}
func (*Client) Get ¶
Get makes a GET request to the specified path. It is a convenience wrapper around Request for retrieving resources.
func (*Client) Post ¶
Post makes a POST request to the specified path with a JSON body. It is a convenience wrapper around Request for creating resources.
func (*Client) Put ¶
Put makes a PUT request to the specified path with a JSON body. It is a convenience wrapper around Request for updating resources.
func (*Client) Request ¶
func (c *Client) Request(ctx context.Context, method, path string, body any) (*http.Response, error)
Request makes an HTTP request to the API with JSON body serialization. It constructs the full URL from the base URL and path, serializes the body as JSON (if provided), and includes authentication headers. The caller is responsible for closing the response body.
func (*Client) RequestRaw ¶
func (c *Client) RequestRaw(ctx context.Context, method, path string, body io.Reader, headers map[string]string) (*http.Response, error)
RequestRaw makes an HTTP request with a raw body and custom headers. Unlike Request, this method does not serialize the body as JSON, making it suitable for multipart form uploads and other non-JSON content types. Custom headers can be provided to set Content-Type and other headers.
func (*Client) SetEnvironment ¶
SetEnvironment changes the environment ID for subsequent requests. This allows switching between different Arcane environments without creating a new client instance.
func (*Client) SetTimeout ¶
SetTimeout changes the timeout for subsequent requests.
func (*Client) TestConnection ¶
TestConnection tests the API connection by making a request to the version endpoint. It returns nil if the connection is successful, or an error describing the failure. This is useful for verifying configuration before making other API calls.
type PaginatedResponse ¶
type PaginatedResponse[T any] struct { Items []T `json:"items"` Pagination struct { CurrentPage int `json:"currentPage"` PageSize int `json:"pageSize"` TotalItems int64 `json:"totalItems"` TotalPages int `json:"totalPages"` } `json:"pagination"` }
PaginatedResponse wraps paginated API responses. It includes the list of items for the current page along with pagination metadata including current page, page size, total items, and total pages.
func DecodePaginatedResponse ¶
func DecodePaginatedResponse[T any](resp *http.Response) (*PaginatedResponse[T], error)
DecodePaginatedResponse decodes a paginated API response. It reads the response body and unmarshals it into a PaginatedResponse containing the items array and pagination metadata. Note: This function closes the response body.
Source Files