Skip to content

Commit

Permalink
readme update for v1.5 release
Browse files Browse the repository at this point in the history
  • Loading branch information
@jeevatkm
jeevatkm committed May 6, 2018
1 parent cc76f53 commit f0976a8
Showing 1 changed file with 68 additions and 18 deletions.
86 changes: 68 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,19 @@
# Resty [![Build Status](https://travis-ci.org/go-resty/resty.svg?branch=master)](https://travis-ci.org/go-resty/resty) [![codecov](https://codecov.io/gh/go-resty/resty/branch/master/graph/badge.svg)](https://codecov.io/gh/go-resty/resty/branch/master) [![GoReport](https://goreportcard.com/badge/go-resty/resty)](https://goreportcard.com/report/go-resty/resty) [![Version](https://img.shields.io/badge/version-1.4-blue.svg)](https://github.com/go-resty/resty/releases/latest) [![GoDoc](https://godoc.org/github.com/go-resty/resty?status.svg)](https://godoc.org/github.com/go-resty/resty) [![License](https://img.shields.io/github/license/go-resty/resty.svg)](LICENSE)
<p align="center">
<h1 align="center">Resty</h1>
<p align="center">Simple HTTP and REST client library for Go</p>
<p align="center"><a href="#features">Features</a> section describes in detail about Resty capabilities</p>
</p>
<p align="center">
<p align="center"><a href="https://travis-ci.org/go-resty/resty"><img src="https://travis-ci.org/go-resty/resty.svg?branch=master" alt="Build Status"></a> <a href="https://codecov.io/gh/go-resty/resty/branch/master"><img src="https://codecov.io/gh/go-resty/resty/branch/master/graph/badge.svg" alt="Code Coverage"></a> <a href="https://goreportcard.com/report/go-resty/resty"><img src="https://goreportcard.com/badge/go-resty/resty" alt="Go Report Card"></a> <a href="https://github.com/go-resty/resty/releases/latest"><img src="https://img.shields.io/badge/version-1.5-blue.svg" alt="Release Version"></a> <a href="https://godoc.org/github.com/go-resty/resty"><img src="https://godoc.org/github.com/go-resty/resty?status.svg" alt="GoDoc"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/go-resty/resty.svg" alt="License"></a></p>
</p>

## News

Simple HTTP and REST client for Go inspired by Ruby rest-client. [Features](#features) section describes in detail about Resty capabilities.
* v1.5 [released](https://github.com/go-resty/resty/releases/latest) and tagged on May 06, 2018.
* v1.0 released - Resty's first version was released on Sep 15, 2015 then it grew gradually as a very handy and helpful library. Its been a two years; `v1.0` was released on Sep 25, 2017. I'm very thankful to Resty users and its [contributors](https://github.com/go-resty/resty/graphs/contributors).

***v1.4 [released](https://github.com/go-resty/resty/releases/latest) and tagged on Apr 04, 2018.***
## Features

*Since Go v1.6 HTTP/2 & HTTP/1.1 protocol is used transparently. `Resty` works fine with HTTP/2 and HTTP/1.1.*

#### v1.0 Released

Resty first version released on Sep 15, 2015 then it grew gradually as a very handy and helpful library. Its been a two years; `v1.0` released on Sep 25, 2017. I'm very thankful to Resty users and its [contributors](https://github.com/go-resty/resty/graphs/contributors).

#### Features
* GET, POST, PUT, DELETE, HEAD, PATCH and OPTIONS
* Simple and chainable methods for settings and request
* Request Body can be `string`, `[]byte`, `struct`, `map`, `slice` and `io.Reader` too
Expand Down Expand Up @@ -54,12 +56,16 @@ Resty first version released on Sep 15, 2015 then it grew gradually as a very ha
* goroutine concurrent safe
* REST and HTTP modes
* Debug mode - clean and informative logging presentation
* Gzip - I'm not doing anything here. Go does it automatically
* Gzip - Go does it automatically also resty fallback handling too
* Works fine with `HTTP/2` and `HTTP/1.1`
* [Bazel support](#bazel-support)
* Easily mock resty for testing, [for e.g.](#mocking-http-requests-using-httpmock-library)
* Well tested client library

Resty works with `go1.3` and above.

#### Included Batteries
### Included Batteries

* Redirect Policies - see [how to use](#redirect-policy)
* NoRedirectPolicy
* FlexibleRedirectPolicy
Expand All @@ -72,13 +78,18 @@ Resty works with `go1.3` and above.
* etc (upcoming - throw your idea's [here](https://github.com/go-resty/resty/issues)).

## Installation

#### Stable Version - Production Ready

Please refer section [Versioning](#versioning) for detailed info.

```sh
# install the library
go get -u gopkg.in/resty.v1
```

#### Latest Version - Development Edge

```sh
# install the latest & greatest library
go get -u github.com/go-resty/resty
Expand All @@ -92,14 +103,17 @@ Resty author also published following projects for Go Community.
* [go-model](https://github.com/jeevatkm/go-model) - Robust & Easy to use model mapper and utility methods for Go `struct`.

## Usage

The following samples will assist you to become as comfortable as possible with resty library. Resty comes with ready to use DefaultClient.

Import resty into your code and refer it as `resty`.

```go
import "gopkg.in/resty.v1"
```

#### Simple GET

```go
// GET request
resp, err := resty.R().Get("http://httpbin.org/get")
Expand Down Expand Up @@ -131,7 +145,9 @@ Response Body: {
}
*/
```

#### Enhanced GET

```go
resp, err := resty.R().
SetQueryParams(map[string]string{
Expand All @@ -155,6 +171,7 @@ resp, err := resty.R().
```

#### Various POST method combinations

```go
// POST JSON string
// No need to set content type, if you have client level setting
Expand Down Expand Up @@ -203,7 +220,9 @@ resp, err := resty.R().
```

#### Sample PUT

You can use various combinations of `PUT` method call like demonstrated for `POST`.

```go
// Note: This is one sample of PUT method usage, refer POST for more combination

Expand All @@ -222,7 +241,9 @@ resp, err := resty.R().
```

#### Sample PATCH

You can use various combinations of `PATCH` method call like demonstrated for `POST`.

```go
// Note: This is one sample of PUT method usage, refer POST for more combination

Expand All @@ -238,6 +259,7 @@ resp, err := resty.R().
```

#### Sample DELETE, HEAD, OPTIONS

```go
// DELETE a article
// No need to set auth token, error, if you have client level settings
Expand Down Expand Up @@ -269,7 +291,9 @@ resp, err := resty.R().
```

### Multipart File(s) upload

#### Using io.Reader

```go
profileImgBytes, _ := ioutil.ReadFile("/Users/jeeva/test-img.png")
notesBytes, _ := ioutil.ReadFile("/Users/jeeva/text-file.txt")
Expand All @@ -285,6 +309,7 @@ resp, err := dclr().
```

#### Using File directly from Path

```go
// Single file scenario
resp, err := resty.R().
Expand Down Expand Up @@ -315,7 +340,8 @@ resp, err := resty.R().
Post("http://myapp.com/profile")
```

#### Sample Form submision
#### Sample Form submission

```go
// just mentioning about POST as an example with simple flow
// User Login
Expand Down Expand Up @@ -346,6 +372,7 @@ resp, err := resty.R().
```

#### Save HTTP Response into File

```go
// Setting output directory path, If directory not exists then resty creates one!
// This is optional one, if you're planning using absoule path in
Expand All @@ -365,6 +392,7 @@ _, err := resty.R().
```

#### Request URL Path Params

Resty provides easy to use dynamic request URL path params. Params can be set at client and request level. Client level params value can be overridden at request level.

```go
Expand All @@ -379,7 +407,9 @@ Get("/v1/users/{userId}/{subAccountId}/details")
```

#### Request and Response Middleware

Resty provides middleware ability to manipulate for Request and Response. It is more flexible than callback approach.

```go
// Registering Request Middleware
resty.OnBeforeRequest(func(c *resty.Client, req *resty.Request) error {
Expand All @@ -399,7 +429,9 @@ resty.OnAfterResponse(func(c *resty.Client, resp *resty.Response) error {
```

#### Redirect Policy

Resty provides few ready to use redirect policy(s) also it supports multiple policies together.

```go
// Assign Client Redirect Policy. Create one as per you need
resty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(15))
Expand All @@ -410,7 +442,9 @@ resty.SetRedirectPolicy(resty.FlexibleRedirectPolicy(20),
```

##### Custom Redirect Policy

Implement [RedirectPolicy](redirect.go#L20) interface and register it with resty client. Have a look [redirect.go](redirect.go) for more information.

```go
// Using raw func into resty.SetRedirectPolicy
resty.SetRedirectPolicy(resty.RedirectPolicyFunc(func(req *http.Request, via []*http.Request) error {
Expand Down Expand Up @@ -438,7 +472,8 @@ func (c *CustomRedirectPolicy) Apply(req *http.Request, via []*http.Request) err
resty.SetRedirectPolicy(CustomRedirectPolicy{/* initialize variables */})
```

#### Custom Root Certificates and Client Certifcates
#### Custom Root Certificates and Client Certificates

```go
// Custom Root certificates, just supply .pem file.
// you can add one or more root certificates, its get appended
Expand All @@ -460,23 +495,27 @@ resty.SetCertificates(cert1, cert2, cert3)
```

#### Proxy Settings - Client as well as at Request Level

Default `Go` supports Proxy via environment variable `HTTP_PROXY`. Resty provides support via `SetProxy` & `RemoveProxy`.
Choose as per your need.

**Client Level Proxy** settings applied to all the request

```go
// Setting a Proxy URL and Port
resty.SetProxy("http://proxyserver:8888")

// Want to remove proxy setting
resty.RemoveProxy()
```

#### Retries

Resty uses [backoff](http://www.awsarchitectureblog.com/2015/03/backoff.html)
to increase retry intervals after each attempt.

Usage example:

```go
// Retries are configured per client
resty.
Expand Down Expand Up @@ -515,6 +554,7 @@ It is also possible to use `resty.Backoff(...)` to get arbitrary retry scenarios
implemented. [Reference](retry_test.go).

#### Choose REST or HTTP mode

```go
// REST mode. This is Default.
resty.SetRESTMode()
Expand All @@ -524,12 +564,14 @@ resty.SetHTTPMode()
```

#### Allow GET request with Payload

```go
// Allow GET request with Payload. This is disabled by default.
resty.SetAllowGetMethodPayload(true)
```

#### Wanna Multiple Clients

```go
// Here you go!
// Client 1
Expand All @@ -546,6 +588,7 @@ client1.R().Head("http://httpbin.org")
```

#### Remaining Client Settings & its Options

```go
// Unique settings at Client level
//--------------------------------
Expand Down Expand Up @@ -652,27 +695,34 @@ In order to mock the http requests when testing your application you
could use the `httpmock` library.

When using the default resty client, you should pass the client to the library as follow:

```go
httpmock.ActivateNonDefault(resty.DefaultClient.GetClient())
```

More detailed example of mocking resty http requests using ginko could be found [here](https://github.com/jarcoal/httpmock#ginkgo--resty-example).

## Versioning

resty releases versions according to [Semantic Versioning](http://semver.org)

`gopkg.in/resty.vX` points to appropriate tag versions; `X` denotes version number and it's a stable release. It's recommended to use version, for eg. `gopkg.in/resty.v0`. Development takes place at the master branch. Although the code in master should always compile and test successfully, it might break API's. We aim to maintain backwards compatibility, but API's and behaviour might be changed to fix a bug.
* `gopkg.in/resty.vX` points to appropriate tagged versions; `X` denotes version series number and it's a stable release for production use. For e.g. `gopkg.in/resty.v0`.
* Development takes place at the master branch. Although the code in master should always compile and test successfully, it might break API's. I aim to maintain backwards compatibility, but sometimes API's and behavior might be changed to fix a bug.

## Contribution

## Contributing
Welcome! If you find any improvement or issue you want to fix, feel free to send a pull request, I like pull requests that include test cases for fix/enhancement. I have done my best to bring pretty good code coverage. Feel free to write tests.
I would welcome your contribution! If you find any improvement or issue you want to fix, feel free to send a pull request, I like pull requests that include test cases for fix/enhancement. I have done my best to bring pretty good code coverage. Feel free to write tests.

BTW, I'd like to know what you think about `Resty`. Kindly open an issue or send me an email; it'd mean a lot to me.

## Author
## Creator

[Jeevanandam M.](https://github.com/jeevatkm) ([email protected])

## Contributors

Have a look on [Contributors](https://github.com/go-resty/resty/graphs/contributors) page.

## License

Resty released under MIT license, refer [LICENSE](LICENSE) file.

0 comments on commit f0976a8

Please sign in to comment.