apiclient

README

API client

API client is a helper for working with REST APIs that you consume. It provides means for authentication, session management and requests/parsing of payload.

Authentication

To implement authentication, just add the appropriate authentication type when you create the session object. If the existing authentication methods does not suit your need, you can either extend with your own type, or just add the headers that are needed as part of the request.

These authentication schemes are supported out of the box:

• basic auth
• authorization

Its extensible model allows for adaption to almost any kind of authentication.

Example

This example sets the base URL, with no extra options. In the request we add some parameters, resulting in https://v2.jokeapi.dev/joke/Any?type=single being called.

session := NewSession("https://v2.jokeapi.dev/joke")
resp, err := session.
	NewRequest(http.MethodGet, "Any?type=single").
	WithContext(context.TODO()).
	Do()

In this example we get the response parsed before it is returned. This is nice if the response struct is known in advance.

session := NewSession("https://v2.jokeapi.dev/joke")
req := session.NewRequest(http.MethodGet, "Any?type=single")
joke, resp, err := RequestWithResponse[utils.Sv443Joke](req)

Documentation

Index

• Constants
• func RequestWithResponse[T any](r *Request) (response T, httpResponse *http.Response, err error)
• type Auth
• type Option
  • func WithAuthorization(kind, value string) Option
  • func WithBasicAuth(username, password string) Option
  • func WithClient(client *http.Client) Option
  • func WithHeaders(headers map[string]string) Option
  • func WithPostHook(postHook func(*http.Response) error) Option
  • func WithPreHook(preHook func(*http.Request) error) Option
• type Request
  • func (r *Request) Do() (*http.Response, error)
  • func (r *Request) WithBody(body io.Reader) *Request
  • func (r *Request) WithContext(ctx context.Context) *Request
  • func (r *Request) WithExtraHeaders(headers map[string]string) *Request
  • func (r *Request) WithJsonBody(body interface{}) *Request
  • func (r *Request) WithPostHook(hook func(req *http.Response) error) *Request
  • func (r *Request) WithPreHook(hook func(req *http.Request) error) *Request
• type Session
  • func NewSession(baseUrl string, opts ...Option) *Session
  • func (s *Session) NewRequest(method, urlStr string) *Request

Constants

const (
	AuthorizationHeader = "Authorization"
	AuthToken           = "Token"
	AuthBearer          = "Bearer"
)

Functions

func RequestWithResponse

func RequestWithResponse[T any](r *Request) (response T, httpResponse *http.Response, err error)

RequestWithResponse performs a request, parses the response body and returns it.

Types

type Auth

type Auth interface {
	AddAuth(r *http.Request) error // this adds authentication to the requested request object
}

Auth represent different kinds of authentication.

type Option

type Option interface {
	SetOption(session *Session) // sets an option
}

Option defines an Option to the session object

func WithAuthorization

func WithAuthorization(kind, value string) Option

WithAuthorization adds "Authorization: kind value" to the request

func WithBasicAuth

func WithBasicAuth(username, password string) Option

WithBasicAuth returns an option that uses strict username and password

func WithClient

func WithClient(client *http.Client) Option

func WithHeaders

func WithHeaders(headers map[string]string) Option

func WithPostHook

func WithPostHook(postHook func(*http.Response) error) Option

WithPostHook adds a hook that is called just after we got the response

func WithPreHook

func WithPreHook(preHook func(*http.Request) error) Option

WithPreHook adds a hook that is called just before the request

type Request

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

Request represents a request against the server

func (*Request) Do

func (r *Request) Do() (*http.Response, error)

Do perform the request and returns the response

func (*Request) WithBody

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

WithBody adds a body to the request

func (*Request) WithContext

func (r *Request) WithContext(ctx context.Context) *Request

WithContext adds a context to the request.

func (*Request) WithExtraHeaders

func (r *Request) WithExtraHeaders(headers map[string]string) *Request

WithExtraHeaders adds extra headers to this request. They are added after the headers from the session object.

func (*Request) WithJsonBody

func (r *Request) WithJsonBody(body interface{}) *Request

WithJsonBody tries to JSON marshal the body and add it to the request. If it fails, an error is printed to the console.

func (*Request) WithPostHook

func (r *Request) WithPostHook(hook func(req *http.Response) error) *Request

func (*Request) WithPreHook

func (r *Request) WithPreHook(hook func(req *http.Request) error) *Request

type Session

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

func NewSession

func NewSession(baseUrl string, opts ...Option) *Session

NewSession creates a new session object

func (*Session) NewRequest

func (s *Session) NewRequest(method, urlStr string) *Request

NewRequest creates a new request object to perform a request on