lra

README

lra - a lowlevel REST api client

This package handles REST API calls and allows for using http and socks proxies as well as self signed certificates. It also allows the specification of headers to be sent with every request.

I wrote this after copying code for various tools connecting to different REST APIs. It consolidates the low level functionality of establishing/configuring a connction and doing the HTTP requests.

License

BSD 3-clause license

Contributions

Contributions / Pull requests are welcome.

Documentation

https://godoc.org/github.com/joernott/lra

Usage

Create connection

A new connection can pe created using the NewConnection function

	hl := make(lra.HeaderList)
	hl["Content-Type"] = "application/json"
	connection,err := lra.NewConnection(
		true,                             // use SSL
		"elasticsearch.example.com",      // server name
		9200,                             // port
		"",                               // no additional base endpoint
		"admin",                          // user name
		"1234",                           // password
		false,                            // we use a certificate generatewd by the elasticsearch CA
		"https://proxy.example.com:3128", // We use a proxy
		false,                            // it is not a socks5 proxy
		hl                                // We want to pass those headers
	)

Get a result

Getting a raw []byte:

  statusRaw,err := connection.Get("/_cluster/health")

Getting parsed JSON:

  statusJson,err := connection.GetJSON("/_cluster/health")

Other API functions

Currently the standard CRUD operations DELETE, GET, PUT, POST are implemented. In addition, CONNECT, HEAD, OPTIONS, PATCH and TRACE are implemented but so far, I didn't need them. So they have not been battle-tested.

For every type, there is a function returning the raw []byte data and a function with the suffix JSON which attempts to parse the data into a json map[string]interface{}.

Documentation

Index

• type Connection
  • func NewConnection(UseSSL bool, Server string, Port int, BaseEndpoint string, User string, ...) (*Connection, error)
  • func (connection *Connection) Connect(endpoint string) ([]byte, error)
  • func (connection *Connection) ConnectJSON(endpoint string, data interface{}) error
  • func (connection *Connection) Delete(endpoint string, jsonData []byte) ([]byte, error)
  • func (connection *Connection) DeleteJSON(endpoint string, jsonData []byte, data interface{}) error
  • func (connection *Connection) Get(endpoint string) ([]byte, error)
  • func (connection *Connection) GetJSON(endpoint string, data interface{}) error
  • func (connection *Connection) Head(endpoint string) ([]byte, error)
  • func (connection *Connection) HeadJSON(endpoint string, data interface{}) error
  • func (connection *Connection) Options(endpoint string) ([]byte, error)
  • func (connection *Connection) OptionsJSON(endpoint string, data interface{}) error
  • func (connection *Connection) Patch(endpoint string, jsonData []byte) ([]byte, error)
  • func (connection *Connection) PatchJSON(endpoint string, jsonData []byte, data interface{}) error
  • func (connection *Connection) Post(endpoint string, jsonData []byte) ([]byte, error)
  • func (connection *Connection) PostJSON(endpoint string, jsonData []byte, data interface{}) error
  • func (connection *Connection) Put(endpoint string, jsonData []byte) ([]byte, error)
  • func (connection *Connection) PutJSON(endpoint string, jsonData []byte, data interface{}) error
  • func (connection *Connection) Trace(endpoint string) ([]byte, error)
  • func (connection *Connection) TraceJSON(endpoint string, data interface{}) error
• type HeaderList

Types

type Connection

type Connection struct {
	Protocol     string
	Server       string
	Port         int
	BaseEndpoint string
	User         string
	Password     string
	ValidateSSL  bool
	Proxy        string
	ProxyIsSocks bool
	BaseURL      string
	SendHeaders  HeaderList
	Client       *http.Client
	Timeout      time.Duration
}

The Connection object stores all the information needed to handle requests. Apart from the http.Client, it also contains the original settings and additional headers to send with every request.

The fields are mostly set by the parameters passed to the NewConnection function except for Protocol, BaseURL and Client which are constructed based on those informations.

func NewConnection

func NewConnection(UseSSL bool, Server string, Port int, BaseEndpoint string, User string, Password string, ValidateSSL bool, Proxy string, ProxyIsSocks bool, SendHeaders HeaderList, Timeout time.Duration) (*Connection, error)

NewConnection builds a Connection object with a configured http client.

Protocol can either be http or https, Server and Port specify the server name or IP and the port to connect to. The BaseEndpoint is added directly behind the port which allows skipping some base path before the api itself, User and Password are used to pass authentication in the URL (like http://admin:1234@localhost:8000/). ValidateSSL, if set to false, allows to skip SSL validation, which is needed for self signed certificates. If ProxyIsSocks is set to true, Proxy is the URL of a SOCKS5 proxy, if set to false it is the URL of a HTTP proxy to use SendHeaders is a list of Headers to send with the requests. This allows to pass authentication headers, content type definitions etc.

func (*Connection) Connect

func (connection *Connection) Connect(endpoint string) ([]byte, error)

Connect issues a HTTP CONNECT request and returns the raw data.

func (*Connection) ConnectJSON

func (connection *Connection) ConnectJSON(endpoint string, data interface{}) error

ConnectJSON issues a HTTP Connect request, parses the resulting data as JSON and returns the parse results.

func (*Connection) Delete

func (connection *Connection) Delete(endpoint string, jsonData []byte) ([]byte, error)

Delete issues a HTTP DELETE request and returns the raw data.

func (*Connection) DeleteJSON

func (connection *Connection) DeleteJSON(endpoint string, jsonData []byte, data interface{}) error

DeleteJSON issues a HTTP DELETE request, parses the resulting data as JSON and returns the parse results.

func (*Connection) Get

func (connection *Connection) Get(endpoint string) ([]byte, error)

Get issues a HTTP GET request and returns the raw data.

func (*Connection) GetJSON

func (connection *Connection) GetJSON(endpoint string, data interface{}) error

GetJSON issues a HTTP GET request, parses the resulting data as JSON and returns the parse results.

func (*Connection) Head

func (connection *Connection) Head(endpoint string) ([]byte, error)

Head issues a HTTP HEAD request and returns the raw data.

func (*Connection) HeadJSON

func (connection *Connection) HeadJSON(endpoint string, data interface{}) error

HeadJSON issues a HTTP HEAD request, parses the resulting data as JSON and returns the parse results.

func (*Connection) Options

func (connection *Connection) Options(endpoint string) ([]byte, error)

Options issues a HTTP OPTIONS request and returns the raw data.

func (*Connection) OptionsJSON

func (connection *Connection) OptionsJSON(endpoint string, data interface{}) error

OptionsJSON issues a HTTP OPTIONS request, parses the resulting data as JSON and returns the parse results.

func (*Connection) Patch

func (connection *Connection) Patch(endpoint string, jsonData []byte) ([]byte, error)

Patch issues a HTTP PATCH (RFC 5789) request and returns the raw data.

func (*Connection) PatchJSON

func (connection *Connection) PatchJSON(endpoint string, jsonData []byte, data interface{}) error

PatchJSON issues a HTTP PATCH request, parses the resulting data as JSON and returns the parse results.

func (*Connection) Post

func (connection *Connection) Post(endpoint string, jsonData []byte) ([]byte, error)

Post issues a HTTP POST request and returns the raw data.

func (*Connection) PostJSON

func (connection *Connection) PostJSON(endpoint string, jsonData []byte, data interface{}) error

PostJSON issues a HTTP POST request, parses the resulting data as JSON and returns the parse results.

func (*Connection) Put

func (connection *Connection) Put(endpoint string, jsonData []byte) ([]byte, error)

Put issues a HTTP PUT request and returns the raw data.

func (*Connection) PutJSON

func (connection *Connection) PutJSON(endpoint string, jsonData []byte, data interface{}) error

PutJSON issues a HTTP PUT request, parses the resulting data as JSON and returns the parse results.

func (*Connection) Trace

func (connection *Connection) Trace(endpoint string) ([]byte, error)

Trace issues a HTTP TRACE request and returns the raw data.

func (*Connection) TraceJSON

func (connection *Connection) TraceJSON(endpoint string, data interface{}) error

TraceJSON issues a HTTP TRACE request, parses the resulting data as JSON and returns the parse results.

type HeaderList

type HeaderList map[string]string

HeaderList is a key-value list of headers to set on every request. Used when declaring the connection.