resthelp

README

Simplified wrapper for calling REST-APIs

Installation

go get github.com/AB-Lindex/go-resthelp

Examples

Create a helper

helper,err := resthelp.New(
  resthelp.WithBaseURL("https://some-custom-api.com"),
  resthelp.WithHeader("Authentication", "Bearer " + token),
)

Create a Request

// Simple GET request with a query parameter
req,err := helper.Get("/users",
  resthelp.WithQuery("page", "2"),
)

// Simple POST with a JSON body
var body myStruct
req,err := helper.Post("/users",
  resthelp.WithJSON(&body),
)

Execute a Request and handle the Response

// Execute the request
resp,err := req.Do()
defer resp.Close()     // always close the response (this is nil-safe)
if !resp.IsOK() {      // this checks for 'err' or anything except 2xx
  panic(resp.Error())  // will either return 'err' or the status-text
}
var data myReponseStruct
err = resp.Parse(data) // will parse the response body into 'data' according to Content-Type

Documentation

Index

• func WithBaseURL(base string) func(*Helper)
• func WithBasicAuth(username, password string) func(*Helper)
• func WithBody(body io.Reader) func(*Request)
• func WithContentType(ct string) func(*Request)
• func WithHeader(k, v string) func(*Helper)
• func WithJSON(v interface{}) func(*Request)
• func WithParser(mimeType string, fn Parser) func(*Helper)
• func WithQuery(k, v string) func(*Request)
• func WithRequestHeader(k, v string) func(*Request)
• func WithTimeout(d time.Duration) func(*Helper)
• func WithXML(v interface{}) func(*Request)
• type Helper
  • func New(opts ...HelperOption) *Helper
  • func (h *Helper) Delete(path string, opts ...RequestOption) (*Request, error)
  • func (h *Helper) Get(path string, opts ...RequestOption) (*Request, error)
  • func (h *Helper) NewRequest(method, path string, opts ...RequestOption) (*Request, error)
  • func (h *Helper) Patch(path string, opts ...RequestOption) (*Request, error)
  • func (h *Helper) Post(path string, opts ...RequestOption) (*Request, error)
  • func (h *Helper) Put(path string, opts ...RequestOption) (*Request, error)
• type HelperOption
• type Parser
• type Request
  • func (r *Request) AddHeader(k, v string)
  • func (r *Request) AddQuery(k, v string)
  • func (req *Request) Do() (*Response, error)
  • func (r *Request) Request() string
• type RequestOption
• type Response
  • func (r *Response) BodyBytes() ([]byte, error)
  • func (r *Response) Close()
  • func (r *Response) Error() string
  • func (r *Response) IsOK() bool
  • func (r *Response) Parse(v interface{}) error
  • func (r *Response) ParseContentType() string
  • func (r *Response) ParseJSON(v interface{}) error
  • func (r *Response) ParseXML(v interface{}) error
  • func (r *Response) Status() int

Functions

func WithBaseURL

func WithBaseURL(base string) func(*Helper)

WithBaseURL sets the base URL of the Helper object.

func WithBasicAuth

func WithBasicAuth(username, password string) func(*Helper)

WithBasicAuth sets the Authorization header with the given username and password.

func WithBody

func WithBody(body io.Reader) func(*Request)

WithBody sets the body of the request.

func WithContentType

func WithContentType(ct string) func(*Request)

WithContentType sets the Content-Type header of the request.

func WithHeader

func WithHeader(k, v string) func(*Helper)

WithHeader sets the default header of the Helper object (like same Authorization header)

func WithJSON

func WithJSON(v interface{}) func(*Request)

WithJSON sets the body of the request using JSON of the supplied value.

func WithParser

func WithParser(mimeType string, fn Parser) func(*Helper)

WithParser adds a parser to the Helper object for the given MIME type.

func WithQuery

func WithQuery(k, v string) func(*Request)

WithQuery adds a query-parameter to the request.

func WithRequestHeader

func WithRequestHeader(k, v string) func(*Request)

WithRequestHeader adds a header to the request.

func WithTimeout

func WithTimeout(d time.Duration) func(*Helper)

WithTimeout sets the timeout of http.Client.

func WithXML

func WithXML(v interface{}) func(*Request)

WithXML sets the body of the request using XML of the supplied value.

Types

type Helper

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

Helper is an object that contains the base URL, headers, and client and help you create requests to an API.

func New

func New(opts ...HelperOption) *Helper

New creates a new Helper object with the given options.

func (*Helper) Delete

func (h *Helper) Delete(path string, opts ...RequestOption) (*Request, error)

Delete creates a DELETE request to the given path

func (*Helper) Get

func (h *Helper) Get(path string, opts ...RequestOption) (*Request, error)

Get creates a GET request to the given path

func (*Helper) NewRequest

func (h *Helper) NewRequest(method, path string, opts ...RequestOption) (*Request, error)

NewRequest creates a new Request object with the given options.

func (*Helper) Patch

func (h *Helper) Patch(path string, opts ...RequestOption) (*Request, error)

Patch creates a PATCH request to the given path

func (*Helper) Post

func (h *Helper) Post(path string, opts ...RequestOption) (*Request, error)

Post creates a POST request to the given path

func (*Helper) Put

func (h *Helper) Put(path string, opts ...RequestOption) (*Request, error)

Put creates a PUT request to the given path

type HelperOption

type HelperOption func(*Helper)

HelperOption is a function that modifies the Helper object.

type Parser

type Parser func(interface{}) error

Parser is a function that parses the response body into an object.

type Request

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

Request is how you create a request to an API.

func (*Request) AddHeader

func (r *Request) AddHeader(k, v string)

AddHeader adds a header to the request.

func (*Request) AddQuery

func (r *Request) AddQuery(k, v string)

AddQuery adds a query parameter to the request.

func (*Request) Do

func (req *Request) Do() (*Response, error)

Do executes the request and returns the response.

func (*Request) Request

func (r *Request) Request() string

Request returns the URL of the request.

type RequestOption

type RequestOption func(*Request)

RequestOption is a function that modifies the Request object.

type Response

type Response struct {
	Header http.Header
	// contains filtered or unexported fields
}

Response is the response of a request.

func (*Response) BodyBytes

func (r *Response) BodyBytes() ([]byte, error)

BodyBytes returns the body of the response as a []byte.

func (*Response) Close

func (r *Response) Close()

Close closes the response body. (should always be called after Do())

func (*Response) Error

func (r *Response) Error() string

Error returns the error message of the response (or the status since it's "now" considered an error)

func (*Response) IsOK

func (r *Response) IsOK() bool

IsOK returns true if the response is considered OK.

func (*Response) Parse

func (r *Response) Parse(v interface{}) error

Parse parses the response into the supplied value (using the 'Content-Type' header)

func (*Response) ParseContentType

func (r *Response) ParseContentType() string

ParseContentType returns the simple content-type of the response.

func (*Response) ParseJSON

func (r *Response) ParseJSON(v interface{}) error

ParseJSON parses the response into the supplied value as JSON.

func (*Response) ParseXML

func (r *Response) ParseXML(v interface{}) error

ParseXML parses the response into the supplied value as XML.

func (*Response) Status

func (r *Response) Status() int

Status returns the status code of the response.