Sling
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 or the examples to learn how to compose a Sling into your API client.
Features
Method Setters: Get/Post/Put/Patch/Delete/Head
Add or Set Request Headers
Base/Path: Extend a Sling for different endpoints
Encode structs into URL query parameters
Encode a form or JSON into the Request Body
Receive JSON success or failure responses
Install
Documentation
Read GoDoc
Usage
Use a Sling to set path, method, header, query, or body properties and create an http.Request
.
Path
Use Path
to set or extend the URL for created Requests. Extension means the path will be resolved relative to the existing URL.
Use Get
, Post
, Put
, Patch
, Delete
, Head
, Options
, Trace
, or Connect
which are exactly the same as Path
except they set the HTTP method too.
Headers
Add
or Set
headers for requests created by a Sling.
Query
QueryStruct
Define url tagged structs. Use QueryStruct
to encode a struct as query parameters on requests.
Body
JSON Body
Define JSON tagged structs. Use BodyJSON
to JSON encode a struct as the Body on requests.
Requests will include an application/json
Content-Type header.
Form Body
Define url tagged structs. Use BodyForm
to form url encode a struct as the Body on requests.
Requests will include an application/x-www-form-urlencoded
Content-Type header.
Plain Body
Use Body
to set a plain io.Reader
on requests created by a Sling.
Set a content type header, if desired (e.g. Set("Content-Type", "text/plain")
).
Extend a Sling
Each Sling creates a standard http.Request
(e.g. with some path and query params) each time Request()
is called. You may wish to extend an existing Sling to minimize duplication (e.g. a common client or base url).
Each Sling instance provides a New()
method which creates an independent copy, so setting properties on the child won't mutate the parent Sling.
Without the calls to base.New()
, tweetShowSling
and tweetPostSling
would 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()
.
Sending
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.
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.
Pass a nil successV
or failureV
argument to skip JSON decoding into that value.
Modify a Request
Sling provides the raw http.Request so modifications can be made using standard net/http features. For example, in Go 1.7+ , add HTTP tracing to a request with a context:
Build an API
APIs typically define an endpoint (also called a service) for each type of resource. For example, here is a tiny Github IssueService which lists repository issues.
Example APIs using Sling
Digits dghubble/go-digits
GoSquared drinkin/go-gosquared
Kala ajvb/kala
Parse fergstar/go-parse
Rdio apriendeau/shares
Swagger Generator swagger-api/swagger-codegen
Twitter dghubble/go-twitter
Hacker News mirceamironenco/go-hackernews
Stacksmith jesustinoco/go-smith
Create a Pull Request to add a link to your own API.
Motivation
Many client libraries follow the lead of google/go-github (our inspiration!), but do so by reimplementing logic common to all clients.
This project borrows and abstracts those ideas into a Sling, an agnostic component any API client can use for creating and sending requests.
Contributing
See the Contributing Guide.
License
Last updated