rest

package
v1.30.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package rest provides a JSON-oriented HTTP client with configurable authentication and request setup.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

type Client struct {
	BaseURL    *url.URL
	HTTPClient *http.Client
	// if not nil, call SetUpRequest() just before the Do() call
	SetupRequest func(req *http.Request, c *Client, body []byte)
	// contains filtered or unexported fields
}

Client sends HTTP requests to a REST service and decodes responses.

func NewClient

func NewClient(options ...Option) *Client

NewClient returns a *Client struct, ready to use. Unless options are supplied the base URL defaults to `https://localhost:443`.

func (*Client) Auth

func (c *Client) Auth(ctx context.Context, clientID string, clientSecret config.Secret)

Auth sets up a 2-legged OAUTH2 with client ID and Secret. If clientID is empty just return, allowing callers to call when the value are not set (or empty) not set.

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, endpoint string, request any) (resp *http.Response, err error)

Delete Method

resp.Body will be closed on return, so the caller should not attempt to read from it.

func (*Client) Do added in v1.26.0

func (c *Client) Do(ctx context.Context, method string, endpoint any, request any, response any) (resp *http.Response, err error)

Do executes the given method (GET, POST, PUT, DELETE) with the given endpoint, request and response. Endpoint is either a string or a *url.URL relative to the client base URL. Request is either a struct that can be encoded as query parameters (for GET) or JSON (for POST and PUT) or a string or []byte that is sent as-is. Response is a pointer to a struct that can be decoded from JSON, XML or text, depending on the content-type of the response. On failure, the error will contain the status code and any body returned by the server.

func (*Client) Get

func (c *Client) Get(ctx context.Context, endpoint any, request any, response any) (resp *http.Response, err error)

GET method. On successful return the response body will be closed. endpoint is either a string or a *url.URL relative to the client c base URL.

resp.Body will be closed on return, so the caller should not attempt to read from it.

func (*Client) Post

func (c *Client) Post(ctx context.Context, endpoint any, request any, response any) (resp *http.Response, err error)

Post issues a POST request to the client using endpoint as either a relative path to the base URL in the client, encoding request as a JSON body and decoding any returned body into result, if set. endpoint is either a string or a *url.URL relative to the client c base URL.

resp.Body will be closed on return, so the caller should not attempt to read from it.

func (*Client) Put

func (c *Client) Put(ctx context.Context, endpoint any, request any, response any) (resp *http.Response, err error)

Put method endpoint is either a string or a *url.URL relative to the client c base URL.

resp.Body will be closed on return, so the caller should not attempt to read from it.

func (*Client) SetAuth

func (c *Client) SetAuth(header, value string)

SetAuth sets an explicit authentication header to value for clients that do not use OAUTH etc.

type Option added in v1.27.0

type Option func(*restOptions)

Option configures a Client created by NewClient.

func BaseURL

func BaseURL(baseurl *url.URL) Option

BaseURL sets the root URL used by the REST client. The default is "https://localhost".

func BaseURLString added in v1.14.2

func BaseURLString(baseurl string) Option

BaseURLString sets the root of the REST API URL. The default is "https://localhost"

func HTTPClient

func HTTPClient(client *http.Client) Option

HTTPClient sets the http.Client to use for requests. The default is the default http package client.

func Logger added in v1.26.0

func Logger(logger *slog.Logger) Option

Logger sets the logger used by the REST client. A nil logger disables request logging.

func SetupRequestFunc added in v1.12.1

func SetupRequestFunc(f func(req *http.Request, c *Client, body []byte)) Option

SetupRequestFunc sets a function to call while setting up the request. For example, to add Basic Authentication:

client = rest.NewClient(
        rest.SetupRequestFunc(func(req *http.Request, c *rest.Client, body []byte) {
            req.SetBasicAuth(username, password.String())
        }),
    )

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL