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 ¶
- Variables
- type Client
- type ErrorResponse
- type File
- type Request
- func DeleteRequest(rawUrl string) *Request
- func GetRequest(rawUrl string) *Request
- func HeadRequest(rawUrl string) *Request
- func NewRequest(rawUrl string) *Request
- func OptionsRequest(rawUrl string) *Request
- func PatchRequest(rawUrl string) *Request
- func PostRequest(rawUrl string) *Request
- func PutRequest(rawUrl string) *Request
- func (r *Request) Add(key string, value string) *Request
- func (r *Request) Body(body interface{}) *Request
- func (r *Request) Build() (*http.Request, error)
- func (r *Request) Field(key string, value string) *Request
- func (r *Request) File(name string, file File) *Request
- func (r *Request) Method(method string) *Request
- func (r *Request) Query(key string, value string) *Request
- func (r *Request) Set(key string, value string) *Request
Constants ¶
This section is empty.
Variables ¶
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 (*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 ¶
DeleteRequest creates a request with DELETE method and the given rawUrl.
func GetRequest ¶
GetRequest creates a request with GET method and the given rawUrl.
func HeadRequest ¶
HeadRequest creates a request with HEAD method and the given rawUrl.
func NewRequest ¶
NewRequest creates a new request with a given rawUrl.
func OptionsRequest ¶
Creates a request with HTTP OPTIONS.
func PatchRequest ¶
PatchRequest creates a request with PATCH method and the given rawUrl.
func PostRequest ¶
PostRequest creates a request with POST method and the given rawUrl.
func PutRequest ¶
PutRequest creates a request with PUT method and the given rawUrl.
func (*Request) Add ¶
Add adds the key, value pair to the request header. It appends to any existing values associated with key.
func (*Request) Body ¶
Body sets the request body. Accepted types are string, []byte, io.Reader, or structs to be JSON encodeded.
func (*Request) File ¶
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.
Source Files