api

Documentation

Overview

Package api provides a low-level client to the overkiz api JSON responses are not unmarshalled and are returned as-is.

Index

• type AuthenticationError
  • func NewAuthenticationError(message string) *AuthenticationError
  • func (e *AuthenticationError) Error() string
• type Client
  • func New(username, password, baseURL, sessionID string) (*Client, error)
  • func NewWithHTTPClient(username, password, baseURL, sessionID string, hc *http.Client) (*Client, error)
  • func (c *Client) DoWithAuth(req *http.Request) (*http.Response, error)
  • func (c *Client) Execute(json []byte) (*http.Response, error)
  • func (c *Client) GetActionGroups() (*http.Response, error)
  • func (c *Client) GetDevice(deviceURL string) (*http.Response, error)
  • func (c *Client) GetDeviceState(deviceURL, stateName string) (*http.Response, error)
  • func (c *Client) GetDevices() (*http.Response, error)
  • func (c *Client) GetWithAuth(query string) (*http.Response, error)
  • func (c *Client) ListenerID() string
  • func (c *Client) Login() error
  • func (c *Client) PollEvents() (*http.Response, error)
  • func (c *Client) RefreshStates() error
  • func (c *Client) SessionID() string
  • func (c *Client) SetListenerID(listenerID string)
• type JSONError
  • func (e *JSONError) Error() string
  • func (e *JSONError) Unwrap() error
• type NoRegisteredEventListenerError
  • func NewNoRegisteredEventListenerError(message string) *NoRegisteredEventListenerError
  • func (e *NoRegisteredEventListenerError) Error() string
• type TooManyRequestsError
  • func NewTooManyRequestsError(message string) *TooManyRequestsError
  • func (e *TooManyRequestsError) Error() string

Types

type AuthenticationError

type AuthenticationError struct {
	Code    int
	Message string
}

AuthenticationError contains an http error Code and text Message

func NewAuthenticationError

func NewAuthenticationError(message string) *AuthenticationError

NewAuthenticationError creates a new AuthenticationError

func (*AuthenticationError) Error

func (e *AuthenticationError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client provides methods to make http requests to the api server while making the authentification and session ID renewal transparent.

func New

func New(username, password, baseURL, sessionID string) (*Client, error)

New returns a new Client sessionID is optional and used when caching sessions externally

func NewWithHTTPClient

func NewWithHTTPClient(username, password, baseURL, sessionID string, hc *http.Client) (*Client, error)

NewWithHTTPClient returns a new Client, injecting the HTTP client to use. See New.

func (*Client) DoWithAuth

func (c *Client) DoWithAuth(req *http.Request) (*http.Response, error)

DoWithAuth performs the given request. If an authentication error occurs, it tries to login to renew the sessionID, then tries the request again.

func (*Client) Execute

func (c *Client) Execute(json []byte) (*http.Response, error)

Execute initiates the execution of a group of actions json needs to be marshalled from an ActionGroup

func (*Client) GetActionGroups

func (c *Client) GetActionGroups() (*http.Response, error)

GetActionGroups returns the list of action groups defined on the box

func (*Client) GetDevice

func (c *Client) GetDevice(deviceURL string) (*http.Response, error)

GetDevice returns the raw response to retrieving one device by URL

func (*Client) GetDeviceState

func (c *Client) GetDeviceState(deviceURL, stateName string) (*http.Response, error)

GetDeviceState returns the current state with name for the device with URL deviceURL

func (*Client) GetDevices

func (c *Client) GetDevices() (*http.Response, error)

GetDevices returns the raw response to retrieving all devices

func (*Client) GetWithAuth

func (c *Client) GetWithAuth(query string) (*http.Response, error)

GetWithAuth performs a GET request for the given query which is appended to the baseURL. It tries to renew the session ID if needed.

func (*Client) ListenerID

func (c *Client) ListenerID() string

ListenerID returns the stored listenerID.

func (*Client) Login

func (c *Client) Login() error

Login to the api server to obtain a session ID cookie This is normally called automatically from the methods that need it

func (*Client) PollEvents

func (c *Client) PollEvents() (*http.Response, error)

PollEvents checks for events, using the saved listener and refreshing it if needed

func (*Client) RefreshStates

func (c *Client) RefreshStates() error

RefreshStates tells the server send the state of all devices as events

func (*Client) SessionID

func (c *Client) SessionID() string

SessionID is the latest known sessionID value It can be used for caching sessions externally. Returns an empty string if the session cookie is not set

func (*Client) SetListenerID

func (c *Client) SetListenerID(listenerID string)

SetListenerID overrides the stored listenerID.

type JSONError

type JSONError struct {
	Data []byte
	Err  error
}

JSONError happens when unmarshalling json fails

func (*JSONError) Error

func (e *JSONError) Error() string

func (*JSONError) Unwrap

func (e *JSONError) Unwrap() error

Unwrap returns the wrapped error

type NoRegisteredEventListenerError

type NoRegisteredEventListenerError struct {
	Code    int
	Message string
}

NoRegisteredEventListenerError happens when an event poll is done on an invalid event listener id

func NewNoRegisteredEventListenerError

func NewNoRegisteredEventListenerError(message string) *NoRegisteredEventListenerError

NewNoRegisteredEventListenerError creates a new TooManyRequestsError

func (*NoRegisteredEventListenerError) Error

func (e *NoRegisteredEventListenerError) Error() string

type TooManyRequestsError

type TooManyRequestsError struct {
	Code    int
	Message string
}

TooManyRequestsError is returned when the Login call gets a reject from the API server because too many authentication attempts too place in a short period. In this case a pause needs to be observed before trying again.

func NewTooManyRequestsError

func NewTooManyRequestsError(message string) *TooManyRequestsError

NewTooManyRequestsError creates a new TooManyRequestsError

func (*TooManyRequestsError) Error

func (e *TooManyRequestsError) Error() string