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) Do ¶
Do sends a request and returns a HTTP response whose body is consumed and closed.
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