Doc improvements and fixes

CHANGES.md

@@ -2,20 +2,20 @@
 
 Notable changes between releases.
 
-## v1.0.0-rc (unreleased)
+## v1.0.0 (2015-05-23)
 
 * Added support for receiving and decoding error JSON structs
 * Renamed Sling `JsonBody` setter to `BodyJSON` (breaking)
 * Renamed Sling `BodyStruct` setter to `BodyForm` (breaking)
 * Renamed Sling fields `httpClient`, `method`, `rawURL`, and `header` to be internal (breaking)
+* Changed `Do` and `Receive` to skip response JSON decoding if "application/json" Content-Type is missing
 * Changed `Sling.Receive(v interface{})` to `Sling.Receive(successV, failureV interface{})` (breaking)
     * Previously `Receive` attempted to decode the response Body in all cases
     * Updated `Receive` will decode the response Body into successV for 2XX responses or decode the Body into failureV for other status codes. Pass a nil `successV` or `failureV` to skip JSON decoding into that value.
     * To upgrade, pass nil for the `failureV` argument or consider defining a JSON tagged struct appropriate for the API endpoint. (e.g. `s.Receive(&issue, nil)`, `s.Receive(&issue, &githubError)`)
     * To retain the old behavior, duplicate the first argument (e.g. s.Receive(&tweet, &tweet))
 * Changed `Sling.Do(http.Request, v interface{})` to `Sling.Do(http.Request, successV, failureV interface{})` (breaking)
     * See the changelog entry about `Receive`, the upgrade path is the same.
-* Require responses to have Content-Type containing application/json before attempting JSON decoding in `Recieve`, `ReceiveSuccess` or `Do`.
 * Removed HEAD, GET, POST, PUT, PATCH, DELETE constants, no reason to export them (breaking)
 
 ## v0.4.0 (2015-04-26)

README.md

@@ -6,6 +6,8 @@ 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 [usage](#usage) or the [examples](examples) to learn how to compose a Sling into your API client.
 
+Note: Sling **v1.0** recently introduced some breaking changes. See [changes](CHANGES.md).
+
 ### Features
 
 * Base/Path - path extend a Sling for different endpoints
@@ -31,8 +33,8 @@ Use a Sling to create an `http.Request` with a chained API for setting propertie
 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)
 ```
@@ -54,7 +56,7 @@ req, err := sling.New().Post("http://upload.com/gophers")
 
 ### Headers
 
-`Add` or `Set` headers which should be applied to all Requests created by a Sling.
+`Add` or `Set` headers which should be applied to the Requests created by a Sling.
 
 ```go
 base := sling.New().Base(baseUrl).Set("User-Agent", "Gophergram API Client")
@@ -133,11 +135,14 @@ req, err := twitterBase.New().Post(path).BodyForm(tweetParams).Request()
 
 Requests will include an `application/x-www-form-urlencoded` Content-Type header.
 
-### Extension
+### Extend a 
 
-A Sling is effectively a generator for one kind of `http.Request` (say with some path and query params) so setter calls change the result of `Request()`. 
+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).
 
-Often, you may wish to create a several kinds of requests, which share some common properties (perhaps a common client and base URL). Each Sling instance provides a `New()` method which creates an independent copy. This allows a parent Sling to be extended to avoid repeating common configuration.
+Each Sling instance provides a `New()` method which creates an independent copy, so setting properties on the child won't mutate the parent Sling. 
 
 ```go
 const twitterApi = "https://api.twitter.com/1.1/"
@@ -152,7 +157,10 @@ tweetPostSling := base.New().Post("statuses/update.json").BodyForm(params)
 req, err := tweetPostSling.Request()
 ```
 
-Note that if the calls to `base.New()` were left out, setter calls would mutate the original Sling `base`, which is undesired! We don't intend to send requests to "https://api.twitter.com/1.1/statuses/show.json/statuses/update.json"!
+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()`.
 

doc.go

@@ -1,31 +1,169 @@
 /*
-Package sling is a Go REST client library for creating and sending requests.
+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
+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.
 
-Use a simple Sling to set request properties (Path, QueryParams, etc.) and
-then create a new http.Request by calling Request().
+Usage
 
-	req, err := sling.New().Get("https://example.com").Request()
+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)
 
-Slings are much more powerful though. Use them to create REST clients
-which wrap complex API endpoints. Copy a base Sling with New() to avoid
-repeating common configuration.
+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)
 
-	const twitterApi = "https://https://api.twitter.com/1.1/"
+	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)
 
-	users := base.New().Path("users/")
-	statuses := base.New().Path("statuses/")
+	// 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.
 
-Choose an http method, set query parameters, and send the request.
+	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"`
+	}
 
-	statuses.New().Get("show.json").QueryStruct(params).Receive(tweet)
+	issues := new([]Issue)
+	githubError := new(GithubError)
+	resp, err := githubBase.New().Get(path).QueryStruct(params).Receive(issues, githubError)
+	fmt.Println(issues, githubError, resp, err)
 
-The usage README provides more details about setting headers, query parameters,
-body data, and decoding a typed response after sending.
+Pass a nil successV or failureV argument to skip JSON decoding into that value.
 */
 package sling

sling.go

@@ -45,11 +45,11 @@ func New() *Sling {
 }
 
 // New returns a copy of a Sling for creating a new Sling with properties
-// from a base Sling. For example,
+// from a parent Sling. For example,
 //
-// 	baseSling := sling.New().Client(client).Base("https://api.io/")
-// 	fooSling := baseSling.New().Get("foo/")
-// 	barSling := baseSling.New().Get("bar/")
+// 	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.