rest

package
v0.0.0-...-a4b61b0 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2021 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package rest provides a simple HTTP and REST request builder and client.

Request examples:

// create a simple GET request
req := GetRequest("http://www.example.com")

// set header
req.Set("Accept", "application/json")

// set query parameters
req.Query("foo1", "bar1")
req.Query("foo2", "bar2")

// Build to a HTTP request
req.Build()

// method chaining is also supported
// the above is equal to:
GetRequest("http://www.example.com").
    Set("Accept", "application/json").
    Query("foo1", "bar1").
    Query("foo2", "bar2").
    Build()

// struct body
foo = Foo{Bar: "val"}
PostRequest("http://www.example.com").
    Body(foo)

// String body
PostRequest("http://www.example.com").
    Body("{\"bar\": \"val\"}")

// Stream body
PostRequest("http://www.example.com").
    Body(strings.NewReader("abcde"))

// Multipart POST request
var f *os.File
PostRequest("http://www.example.com").
    Field("foo", "bar").
    File("file1", File{Name: f.Name(), Content: f}).
    File("file2", File{Name: "1.txt", Content: []byte("abcde"), Type: "text/plain"})

Index

Constants

This section is empty.

Variables

View Source
var ErrEmptyResponseBody = errors.New("empty response body")

ErrEmptyResponseBody means the client receives an unexpected empty response from server

Functions

This section is empty.

Types

type Client

type Client struct {
	HTTPClient    *http.Client // HTTP client, default is HTTP DefaultClient
	DefaultHeader http.Header  // Default header applied to all outgoing HTTP request.
}

Client is a simple HTTP and REST client. Create it with NewClient method.

func NewClient

func NewClient() *Client

NewClient creates a client.

func (*Client) Do

func (c *Client) Do(r *Request, respV interface{}, errV interface{}) (*http.Response, error)

Do wraps DoWithContext using the background context.

func (*Client) DoWithContext

func (c *Client) DoWithContext(ctx context.Context, r *Request, respV interface{}, errV interface{}) (*http.Response, error)

DoWithContext sends a request and returns a HTTP response whose body is consumed and closed. The context controls the lifetime of the outgoing request and its response.

If respV is not nil, the value it points to is JSON decoded when server returns a successful response.

If errV is not nil, the value it points to is JSON decoded when server returns an unsuccessfully response. If the response text is not a JSON string, a more generic ErrorResponse error is returned.

type ErrorResponse

type ErrorResponse struct {
	StatusCode int    //  Response status code
	Message    string // Response text
}

ErrorResponse is the status code and response received from the server when an error occurs.

func (*ErrorResponse) Error

func (e *ErrorResponse) Error() string

type File

type File struct {
	// File name
	Name    string    // name of the file to be uploaded
	Content io.Reader // content of the file
	Type    string    // Mime type, default is "application/octet-stream"
}

File represents a file upload in HTTP request

type Request

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

Request represent a REST request. It provides helper functions to build a HTTP request.

func DeleteRequest

func DeleteRequest(rawUrl string) *Request

DeleteRequest creates a request with DELETE method and the given rawUrl.

func GetRequest

func GetRequest(rawUrl string) *Request

GetRequest creates a request with GET method and the given rawUrl.

func HeadRequest

func HeadRequest(rawUrl string) *Request

HeadRequest creates a request with HEAD method and the given rawUrl.

func NewRequest

func NewRequest(rawUrl string) *Request

NewRequest creates a new request with a given rawUrl.

func OptionsRequest

func OptionsRequest(rawUrl string) *Request

Creates a request with HTTP OPTIONS.

func PatchRequest

func PatchRequest(rawUrl string) *Request

PatchRequest creates a request with PATCH method and the given rawUrl.

func PostRequest

func PostRequest(rawUrl string) *Request

PostRequest creates a request with POST method and the given rawUrl.

func PutRequest

func PutRequest(rawUrl string) *Request

PutRequest creates a request with PUT method and the given rawUrl.

func (*Request) Add

func (r *Request) Add(key string, value string) *Request

Add adds the key, value pair to the request header. It appends to any existing values associated with key.

func (*Request) Body

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

Body sets the request body. Accepted types are string, []byte, io.Reader, or structs to be JSON encodeded.

func (*Request) Build

func (r *Request) Build() (*http.Request, error)

Build builds a HTTP request according to the settings in the REST request.

func (*Request) Field

func (r *Request) Field(key string, value string) *Request

Field appends the key, value pair to the form fields in the POST request.

func (*Request) File

func (r *Request) File(name string, file File) *Request

File appends a file upload item in the POST request. The file content will be consumed when building HTTP request (see Build()) and closed if it's also a ReadCloser type.

func (*Request) Method

func (r *Request) Method(method string) *Request

Method sets HTTP method of the request.

func (*Request) Query

func (r *Request) Query(key string, value string) *Request

Query appends the key, value pair to the request query which will be encoded as url query parameters on HTTP request's url.

func (*Request) Set

func (r *Request) Set(key string, value string) *Request

Set sets the header entries associated with key to the single element value. It replaces any existing values associated with key.

Jump to

Keyboard shortcuts

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