apiClient

Documentation

Index

• Variables
• func JSONUnmarshal(data []byte, v interface{}) error
• type BasicAuth
• type Client
  • func New(endpoint string, errorRegistry ErrorRegistry) *Client
  • func (c Client) JSON(method, path string, query url.Values, body io.Reader, response interface{}) (err error)
  • func (c Client) JSONContext(ctx context.Context, method, path string, query url.Values, body io.Reader, ...) (err error)
  • func (c Client) Request(method, path string, query url.Values, body io.Reader, accept []string) (resp *http.Response, err error)
  • func (c Client) RequestContext(ctx context.Context, method, path string, query url.Values, body io.Reader, ...) (resp *http.Response, err error)
  • func (c Client) Stream(method, path string, query url.Values, body io.Reader, accept []string) (data io.ReadCloser, contentType string, err error)
  • func (c Client) StreamContext(ctx context.Context, method, path string, query url.Values, body io.Reader, ...) (data io.ReadCloser, contentType string, err error)
• type Error
  • func (e *Error) Error() string
• type ErrorRegistry
• type MapErrorRegistry
  • func NewMapErrorRegistry(errors map[int]error, handlers map[int]func(body []byte) error) *MapErrorRegistry
  • func (r *MapErrorRegistry) AddError(code int, err error) error
  • func (r *MapErrorRegistry) AddHandler(code int, handler func(body []byte) error) error
  • func (r *MapErrorRegistry) AddMessageError(code int, message string) (*Error, error)
  • func (r MapErrorRegistry) Error(code int) error
  • func (r MapErrorRegistry) Handler(code int) func(body []byte) error
  • func (r *MapErrorRegistry) MustAddError(code int, err error)
  • func (r *MapErrorRegistry) MustAddHandler(code int, handler func(body []byte) error)
  • func (r *MapErrorRegistry) MustAddMessageError(code int, message string) *Error

Variables

var DefaultKeyHeader = "X-Key"

DefaultKeyHeader is default HTTP header name to pass API key when making a request.

var ErrErrorAlreadyRegistered = errors.New("error already registered")

ErrErrorAlreadyRegistered is returned an error with the same code is found in the error registry.

Functions

func JSONUnmarshal

func JSONUnmarshal(data []byte, v interface{}) error

JSONUnmarshal decodes data into v and returns json.SyntaxError and json.UnmarshalTypeError formated with additional information.

Types

type BasicAuth

type BasicAuth struct {
	Username string
	Password string
}

BasicAuth holds information for HTTP Basic Auth.

type Client

type Client struct {
	// Endpoint is an URL of the service. (required)
	Endpoint string
	// Key is a single string that is used in request authorization.
	Key string
	// KeyHeader is HTTP header name used to pass Client.Key value.
	// If it is left blank, DefaultKeyHeader is used.
	KeyHeader string
	// UserAgent is a string that will be passed as a value to User-Agent
	// HTTP header.
	UserAgent string
	// Headers is optional additional headers that will be passed on
	// each request.
	Headers map[string]string
	// BasicAuth holds information for HTTP Basic Auth.
	BasicAuth *BasicAuth
	// ErrorRegistry maps error codes to actual errors. It is used to
	// identify errors from the services and pass them as return values.
	ErrorRegistry ErrorRegistry
	// HTTPClient is net/http.Client to be used for making HTTP requests.
	// If Client is nil, DefaultClient is used.
	HTTPClient *http.Client
}

Client stores properties that defines communication with a HTTP API service.

func New

func New(endpoint string, errorRegistry ErrorRegistry) *Client

New returns a new instance of Client with default values.

func (Client) JSON

func (c Client) JSON(method, path string, query url.Values, body io.Reader, response interface{}) (err error)

JSON makes a HTTP request that expects application/json response. It decodes response body to a `response` argument.

func (Client) JSONContext

func (c Client) JSONContext(ctx context.Context, method, path string, query url.Values, body io.Reader, response interface{}) (err error)

JSONContext provides the same functionality as JSON with Context instance passing to http.Request.

func (Client) Request

func (c Client) Request(method, path string, query url.Values, body io.Reader, accept []string) (resp *http.Response, err error)

Request makes a HTTP request based on Client configuration and arguments provided.

func (Client) RequestContext

func (c Client) RequestContext(ctx context.Context, method, path string, query url.Values, body io.Reader, accept []string) (resp *http.Response, err error)

RequestContext provides the same functionality as Request with Context instance passing to http.Request.

func (Client) Stream

func (c Client) Stream(method, path string, query url.Values, body io.Reader, accept []string) (data io.ReadCloser, contentType string, err error)

Stream makes a HTTP request and returns request body as io.ReadCloser, to be able to read long running responses. Returned io.ReadCloser must be closed at the end of read. To reuse HTTP connection, make sure that the whole data is read before closing the reader.

func (Client) StreamContext

func (c Client) StreamContext(ctx context.Context, method, path string, query url.Values, body io.Reader, accept []string) (data io.ReadCloser, contentType string, err error)

StreamContext provides the same functionality as Stream with Context instance passing to http.Request.

type Error

type Error struct {
	// Message is a text that describes an error.
	Message string `json:"message"`
	// Code is a number that identifies error.
	// It allows error identification when serialization is involved.
	Code int `json:"code"`
}

Error represents an error that contains a message and an error code. If the error is based on HTTP response status, message is status text and code status code.

func (*Error) Error

func (e *Error) Error() string

Error returns a Message value.

type ErrorRegistry

type ErrorRegistry interface {
	Error(int) error
	Handler(int) func(body []byte) error
}

ErrorRegistry defines an interface to retrieve error by a numerical code.

type MapErrorRegistry

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

MapErrorRegistry uses map to store errors and their codes. It is assumed that adding of errors will be performed on initialization of program and therefore it is not locked for concurrent writes. Concurrent reads are safe as Go maps allow it. If concurrent adding and reading of errors in registry is needed, an implementation with locks must be used.

func NewMapErrorRegistry

func NewMapErrorRegistry(errors map[int]error, handlers map[int]func(body []byte) error) *MapErrorRegistry

NewMapErrorRegistry creates a new instance of MapErrorRegistry.

func (*MapErrorRegistry) AddError

func (r *MapErrorRegistry) AddError(code int, err error) error

AddError adds a new error with a code to the registry. It there already is an error or handler with the same code, ErrErrorAlreadyRegistered will be returned.

func (*MapErrorRegistry) AddHandler

func (r *MapErrorRegistry) AddHandler(code int, handler func(body []byte) error) error

AddHandler adds a new error handler with a code to the registry. It there already is an error or handler with the same code, ErrErrorAlreadyRegistered will be returned.

func (*MapErrorRegistry) AddMessageError

func (r *MapErrorRegistry) AddMessageError(code int, message string) (*Error, error)

AddMessageError adds a new Error isntance with a code and message to the registry. It there already is an error or handler with the same code, ErrErrorAlreadyRegistered will be returned.

func (MapErrorRegistry) Error

func (r MapErrorRegistry) Error(code int) error

Error returns an error that is registered under the provided code.

func (MapErrorRegistry) Handler

func (r MapErrorRegistry) Handler(code int) func(body []byte) error

Handler returns a handler that is registered under the provided code.

func (*MapErrorRegistry) MustAddError

func (r *MapErrorRegistry) MustAddError(code int, err error)

MustAddError calls AddError and panics in case of an error.

func (*MapErrorRegistry) MustAddHandler

func (r *MapErrorRegistry) MustAddHandler(code int, handler func(body []byte) error)

MustAddHandler calls AddHandler and panics in case of an error.

func (*MapErrorRegistry) MustAddMessageError

func (r *MapErrorRegistry) MustAddMessageError(code int, message string) *Error

MustAddMessageError calls AddMessageError and panics in case of an error.