Documentation ¶
Overview ¶
Package sling is a Go HTTP client library for creating and sending API requests.
Slings store HTTP Request properties to simplify sending requests and decoding responses. Check the examples to learn how to compose a Sling into your API client.
Usage ¶
Use a Sling to create an http.Request with a chained API for setting properties (path, method, queries, body, etc.).
type Params struct { Count int `url:"count,omitempty"` } params := &Params{Count: 5} req, err := sling.New().Get("https://example.com").QueryStruct(params).Request() client.Do(req)
Path ¶
Use Path to set or extend the URL for created Requests. Extension means the path will be resolved relative to the existing URL.
// sends a GET request to http://example.com/foo/bar req, err := sling.New().Base("http://example.com/").Path("foo/").Path("bar").Request()
Use Get, Post, Put, Patch, Delete, or Head which are exactly the same as Path except they set the HTTP method too.
req, err := sling.New().Post("http://upload.com/gophers")
Headers ¶
Add or Set headers which should be applied to the Requests created by a Sling.
base := sling.New().Base(baseUrl).Set("User-Agent", "Gophergram API Client") req, err := base.New().Get("gophergram/list").Request()
QueryStruct ¶
Define url parameter structs (https://godoc.org/github.com/google/go-querystring/query) and use QueryStruct to encode query parameters.
// Github Issue Parameters type IssueParams struct { Filter string `url:"filter,omitempty"` State string `url:"state,omitempty"` Labels string `url:"labels,omitempty"` Sort string `url:"sort,omitempty"` Direction string `url:"direction,omitempty"` Since string `url:"since,omitempty"` } githubBase := sling.New().Base("https://api.github.com/").Client(httpClient) path := fmt.Sprintf("repos/%s/%s/issues", owner, repo) params := &IssueParams{Sort: "updated", State: "open"} req, err := githubBase.New().Get(path).QueryStruct(params).Request()
Json Body ¶
Make a Sling include JSON in the Body of its Requests using BodyJSON.
type IssueRequest struct { Title string `json:"title,omitempty"` Body string `json:"body,omitempty"` Assignee string `json:"assignee,omitempty"` Milestone int `json:"milestone,omitempty"` Labels []string `json:"labels,omitempty"` } githubBase := sling.New().Base("https://api.github.com/").Client(httpClient) path := fmt.Sprintf("repos/%s/%s/issues", owner, repo) body := &IssueRequest{ Title: "Test title", Body: "Some issue", } req, err := githubBase.New().Post(path).BodyJSON(body).Request()
Requests will include an "application/json" Content-Type header.
Form Body ¶
Make a Sling include a url-tagged struct as a url-encoded form in the Body of its Requests using BodyForm.
type StatusUpdateParams struct { Status string `url:"status,omitempty"` InReplyToStatusId int64 `url:"in_reply_to_status_id,omitempty"` MediaIds []int64 `url:"media_ids,omitempty,comma"` } tweetParams := &StatusUpdateParams{Status: "writing some Go"} req, err := twitterBase.New().Post(path).BodyForm(tweetParams).Request()
Requests will include an "application/x-www-form-urlencoded" Content-Type header.
Extend a Sling ¶
Each distinct Sling generates an http.Request (say with some path and query params) each time Request() is called, based on its state. When creating different kinds of requests using distinct Slings, you may wish to extend an existing Sling to minimize duplication (e.g. a common client).
Each Sling instance provides a New() method which creates an independent copy, so setting properties on the child won't mutate the parent Sling.
const twitterApi = "https://api.twitter.com/1.1/" base := sling.New().Base(twitterApi).Client(httpAuthClient) // statuses/show.json Sling tweetShowSling := base.New().Get("statuses/show.json").QueryStruct(params) req, err := tweetShowSling.Request() // statuses/update.json Sling tweetPostSling := base.New().Post("statuses/update.json").BodyForm(params) req, err := tweetPostSling.Request()
Without the calls to base.New(), tweetShowSling and tweetPostSling reference the base Sling and POST to "https://api.twitter.com/1.1/statuses/show.json/statuses/update.json", which is undesired.
Recap: If you wish to extend a Sling, create a new child copy with New().
Receive ¶
Define a JSON struct to decode a type from 2XX success responses. Use ReceiveSuccess(successV interface{}) to send a new Request and decode the response body into successV if it succeeds.
// Github Issue (abbreviated) type Issue struct { Title string `json:"title"` Body string `json:"body"` } issues := new([]Issue) resp, err := githubBase.New().Get(path).QueryStruct(params).ReceiveSuccess(issues) fmt.Println(issues, resp, err)
Most APIs return failure responses with JSON error details. To decode these, define success and failure JSON structs. Use Receive(successV, failureV interface{}) to send a new Request that will automatically decode the response into the successV for 2XX responses or into failureV for non-2XX responses.
type GithubError struct { Message string `json:"message"` Errors []struct { Resource string `json:"resource"` Field string `json:"field"` Code string `json:"code"` } `json:"errors"` DocumentationURL string `json:"documentation_url"` } issues := new([]Issue) githubError := new(GithubError) resp, err := githubBase.New().Get(path).QueryStruct(params).Receive(issues, githubError) fmt.Println(issues, githubError, resp, err)
Pass a nil successV or failureV argument to skip JSON decoding into that value.
Index ¶
- type Sling
- func (s *Sling) Add(key, value string) *Sling
- func (s *Sling) Base(rawURL string) *Sling
- func (s *Sling) BodyForm(bodyForm interface{}) *Sling
- func (s *Sling) BodyJSON(bodyJSON interface{}) *Sling
- func (s *Sling) Client(httpClient *http.Client) *Sling
- func (s *Sling) Delete(pathURL string) *Sling
- func (s *Sling) Do(req *http.Request, successV, failureV interface{}) (*http.Response, error)
- func (s *Sling) Get(pathURL string) *Sling
- func (s *Sling) Head(pathURL string) *Sling
- func (s *Sling) New() *Sling
- func (s *Sling) Patch(pathURL string) *Sling
- func (s *Sling) Path(path string) *Sling
- func (s *Sling) Post(pathURL string) *Sling
- func (s *Sling) Put(pathURL string) *Sling
- func (s *Sling) QueryStruct(queryStruct interface{}) *Sling
- func (s *Sling) Receive(successV, failureV interface{}) (*http.Response, error)
- func (s *Sling) ReceiveSuccess(successV interface{}) (*http.Response, error)
- func (s *Sling) Request() (*http.Request, error)
- func (s *Sling) Set(key, value string) *Sling
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Sling ¶
type Sling struct {
// contains filtered or unexported fields
}
Sling is an HTTP Request builder and sender.
func (*Sling) Add ¶
Add adds the key, value pair in Headers, appending values for existing keys to the key's values. Header keys are canonicalized.
func (*Sling) Base ¶
Base sets the rawURL. If you intend to extend the url with Path, baseUrl should be specified with a trailing slash.
func (*Sling) BodyForm ¶
BodyForm sets the Sling's bodyForm. The value pointed to by the bodyForm will be url encoded to set the Body on new requests. The bodyStruct argument should be a pointer to a url tagged struct. See https://godoc.org/github.com/google/go-querystring/query for details.
func (*Sling) BodyJSON ¶
BodyJSON sets the Sling's bodyJSON. The value pointed to by the bodyJSON will be JSON encoded to set the Body on new requests (see Request()). The bodyJSON argument should be a pointer to a JSON tagged struct. See https://golang.org/pkg/encoding/json/#MarshalIndent for details.
func (*Sling) Client ¶
Client sets the http Client used to do requests. If a nil client is given, the http.DefaultClient will be used.
func (*Sling) Do ¶
Do sends an HTTP request and returns the response. Success responses (2XX) are JSON decoded into the value pointed to by successV and other responses are JSON decoded into the value pointed to by failureV. Any error sending the request or decoding the response is returned.
func (*Sling) New ¶
New returns a copy of a Sling for creating a new Sling with properties from a parent Sling. For example,
parentSling := sling.New().Client(client).Base("https://api.io/") fooSling := parentSling.New().Get("foo/") barSling := parentSling.New().Get("bar/")
fooSling and barSling will both use the same client, but send requests to https://api.io/foo/ and https://api.io/bar/ respectively.
Note that query and body values are copied so if pointer values are used, mutating the original value will mutate the value within the child Sling.
func (*Sling) Path ¶
Path extends the rawURL with the given path by resolving the reference to an absolute URL. If parsing errors occur, the rawURL is left unmodified.
func (*Sling) QueryStruct ¶
QueryStruct appends the queryStruct to the Sling's queryStructs. The value pointed to by each queryStruct will be encoded as url query parameters on new requests (see Request()). The queryStruct argument should be a pointer to a url tagged struct. See https://godoc.org/github.com/google/go-querystring/query for details.
func (*Sling) Receive ¶
Receive creates a new HTTP request and returns the response. Success responses (2XX) are JSON decoded into the value pointed to by successV and other responses are JSON decoded into the value pointed to by failureV. Any error creating the request, sending it, or decoding the response is returned. Receive is shorthand for calling Request and Do.
func (*Sling) ReceiveSuccess ¶
ReceiveSuccess creates a new HTTP request and returns the response. Success responses (2XX) are JSON decoded into the value pointed to by successV. Any error creating the request, sending it, or decoding a 2XX response is returned.