rest

Documentation

Index

• Variables
• func PathEscape(path string) string
• type Body
• type ClientOpt
  • func AddHeader(key, value string) ClientOpt
  • func REST() ClientOpt
  • func SetAuthentication(authenticator authpkg.Authenticator) ClientOpt
  • func SetHttpClient(httpClient httpclient.HttpClient) ClientOpt
• type ReqOpt
  • func Headers(more http.Header) ReqOpt
  • func HeadersKV(kv ...string) ReqOpt
  • func IfMatch(etag ...header.ETag) ReqOpt
  • func IfModifiedSince(t time.Time) ReqOpt
  • func IfNoneMatch(etag ...header.ETag) ReqOpt
  • func Query(kv ...string) ReqOpt
• type Response
• type RestClient
  • func NewClient(uri string, opts ...ClientOpt) RestClient
• type RestError
  • func (re *RestError) Error() string
  • func (re *RestError) IsPermanent() bool
  • func (re *RestError) IsTransient() bool
  • func (re *RestError) Unwrap() error

Examples

• PathEscape

Variables

var RESTErrorStringLimit = 100

Functions

func PathEscape

func PathEscape(path string) string

PathEscape escapes each segment in the path, leaving the '/' separators intact.

Example

fmt.Println(pathEscape(""))
fmt.Println(pathEscape("/"))
fmt.Println(pathEscape("/web"))
fmt.Println(pathEscape("/web/"))
fmt.Println(pathEscape("/w e b/d a v/s%u&c#k:s/"))

Output:


/
/web
/web/
/w%20e%20b/d%20a%20v/s%25u&c%23k:s/

Types

type Body

type Body interface {
	Bytes() []byte
	fmt.Stringer
	io.Reader
}

type ClientOpt

type ClientOpt func(RestClient)

ClientOpt functions configure the client.

func AddHeader

func AddHeader(key, value string) ClientOpt

AddHeader sets a request header that will be applied to all subsequent requests.

func REST

func REST() ClientOpt

REST sets the following headers typical of REST requests on all requests:

• Accept: application/json
• Accept-Encoding: identity

func SetAuthentication

func SetAuthentication(authenticator authpkg.Authenticator) ClientOpt

SetAuthentication sets the authentication credentials and method. Leave the authenticator method blank to allow HTTP challenges to select an appropriate method. Otherwise it should be "basic".

func SetHttpClient

func SetHttpClient(httpClient httpclient.HttpClient) ClientOpt

SetHttpClient changes the http.Client. This allows control over the http.Transport, timeouts etc.

type ReqOpt

type ReqOpt func(*http.Request)

ReqOpt optionally amends or enhances a request before it is sent.

func Headers

func Headers(more http.Header) ReqOpt

Headers sets more header values on the request. This overwrites any pre-existing headers where they have the same names.

func HeadersKV

func HeadersKV(kv ...string) ReqOpt

HeadersKV adds header values to the request. kv is a list of key & value pairs. Pre-existing headers are added to.

func IfMatch

func IfMatch(etag ...header.ETag) ReqOpt

IfMatch makes a request conditional upon ETags and is typically used for PUT, POST and DELETE requests. There is also an If-Unmodified-Since header, but If-Match takes precedence (see RFC-9110).

func IfModifiedSince

func IfModifiedSince(t time.Time) ReqOpt

IfModifiedSince makes a request conditional upon change history and is typically used for GET requests.

func IfNoneMatch

func IfNoneMatch(etag ...header.ETag) ReqOpt

IfNoneMatch makes a request conditional upon ETags and is typically used for GET requests.

func Query

func Query(kv ...string) ReqOpt

Query adds query values to the request. kv is a list of key & value pairs.

type Response

type Response struct {
	// StatusCode the HTTP status code
	StatusCode int
	// Header the response headers
	Header http.Header
	// Type the content type of the response entity
	Type header.ContentType
	// Body the buffered response entity
	Body *bodypkg.Body
	// Request the original request
	Request *http.Request
}

Response holds an HTTP response with the entity in a buffer.

type RestClient

type RestClient interface {
	Request(ctx context.Context, method, path string, reqBody any, opts ...ReqOpt) (*http.Response, error)
	Head(ctx context.Context, path string, opts ...ReqOpt) (*Response, error)
	Get(ctx context.Context, path string, opts ...ReqOpt) (*Response, error)
	Put(ctx context.Context, path string, reqBody any, opts ...ReqOpt) (*Response, error)
	Post(ctx context.Context, path string, reqBody any, opts ...ReqOpt) (*Response, error)
	Delete(ctx context.Context, path string, reqBody any, opts ...ReqOpt) (*Response, error)
	ClearCookies()
}

RestClient implements HTTP client requests as typically used for REST APIs etc.

The Request method returns a http.Response that may contain a body as an io.ReadCloser, which can be handled appropriately by the caller. The caller must close this body (if the response is not nil).

The Head, Get, Put, Post, and Delete methods return a Response containing a buffered body that is simpler to use but potentially less performant for large bodies.

func NewClient

func NewClient(uri string, opts ...ClientOpt) RestClient

NewClient creates a new Client. By default, this uses the default HTTP client.

type RestError

type RestError struct {
	Response
	Cause error
}

func (*RestError) Error

func (re *RestError) Error() string

Error makes it compatible with `error` interface.

func (*RestError) IsPermanent

func (re *RestError) IsPermanent() bool

IsPermanent returns the opposite of RestError.IsTransient; the request should not be retried.

func (*RestError) IsTransient

func (re *RestError) IsTransient() bool

IsTransient returns true for server/network errors that can be retried. (Note that 401 authentication challenges should be responded to normally).

func (*RestError) Unwrap

func (re *RestError) Unwrap() error