/
doc.go
177 lines (177 loc) · 5.57 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
// Package rest is an extremely simple to use, lightweight, yet powerful REST Client.
//
// Motivation
//
// The Go http standard library is a great library, but it might sometimes be a bit too low level to use,
// and it doesn't offer features like fork-join requests for better performance, response caching based on headers,
// and the possibility to mockup responses.
//
// Features and Roadmap
//
// v0.1
// * GET, POST, PUT, PATCH, DELETE, HEAD & OPTIONS HTTP verbs
// * Dead simple, synchronous requests
// * Automatic caching of transport object and hosts connections
// * Response Caching, based on response headers (cache-control, last-modified, etag, expires)
// * Local caching strategies: TTL, LRU & Max Byte Size.
// * Mockups!
// * Fork-Join request pattern, for sending many requests concurrently, getting better client perfomance.
// * Async request pattern.
// * Request Body can be `string`, `[]byte`, `struct` & `map`
// * Automatic marshal and unmarshal for `JSON` and `XML` Content-Type. Default JSON.
// * Full access to http.Response object.
//
// v0.2
// * Retries
// * BasicAuth
// * UserAgent
//
// v0.3
// * Connection usage metrics
// * Response Time metrics
// * Brotli Content-Encoding Responses support - http://google-opensource.blogspot.com.ar/2015/09/introducing-brotli-new-compression.html
//
// v0.4
// * Custom Root Certificates and Client Certificates
// * Testing +95%
//
// v0.5
// * Plugable external caches like Memcached
//
// Caching
//
// Caching is done by two strategies working together: Time To Live (TTL) and
// Least Recently Used (LRU). Objects are inserted in the cache based on
// Response Headers. You can establish a maximum Memory Size for the cache
// and objects are flushed based on time expiration (TTL) or by hitting the maximum
// memory limit. In the last case, least accessed objects will be removed first.
//
// Examples
//
// Installation
// go get github.com/go-loco/restful/rest
//
// Importing
// import "github.com/go-loco/restful/rest"
//
// Simple GET
// resp := rest.Get("https://api.restfulsite.com/resource")
//
// Simple POST
// // Using a `string` as body
// resp := rest.Post("https://api.restfulsite.com/resource", "Body")
//
//
// Simple POST, with Struct Body
// type User struct {
// Id int `json:"id"`
// Name string `json:"name"`
// }
//
// body := new(User)
// body.Id = 1
// body.Name = "Hernan"
//
// // body will be marshall as JSON
// resp := rest.Post("https://api.restfulsite.com/resource/1", body)
// fmt.Println(resp)
//
// Fork Join
//
// ForkJoin let you **fork** requests, and **wait** until all of them have return.
//
// Concurrent has methods for Get, Post, Put, Patch, Delete, Head & Options,
// with the almost the same API as the synchronous methods.
// The difference is that these methods return a FutureResponse, which holds a pointer to
// Response. Response inside FutureResponse is nil until request has finished.
//
// var f [3]*rest.FutureResponse
//
// // ForkJoin will send all requests concurrently
// // and will wait until all requests have their correspondent responses
// rest.ForkJoin(func(c *rest.Concurrent) {
// f[0] = c.Get("https://api.restfulsite.com/resource/1")
// f[1] = c.Get("https://api.restfulsite.com/resource/2")
// f[2] = c.Get("https://api.restfulsite.com/resource/3")
// })
//
// for i := range f {
// if f[i].Response().StatusCode == http.StatusOK {
// fmt.Println(f[i].Response())
// }
// }
//
// Async
//
// Async let you make Restful requests in an **asynchronous** way, without blocking
// the go routine calling the Async function.
//
// Whenever the Response is ready, the **f** function will be called back.
//
// // This won't be blocked.
// rest.AsyncGet("https://api.restfulsite.com/user", func(r *rest.Response) {
// if r.StatusCode == http.StatusOK {
// fmt.Println(r)
// }
// })
//
// // This will be printed first.
// fmt.Println("print first")
//
// Defaults
// * Headers: keep-alive, Cache-Control: no-cache
// * Timeout: 2 seconds
// * ContentType: JSON (for body requests in POST, PUT and PATCH)
// * Cache: enable
// * Cache Size: 1GB
// * Idle Connections Per Host: 2 (the default of http.net package)
// * HTTP/2: automatic with Go 1.6
// * Gzip: automatic support for gzip responses
//
// RequestBuilder
//
// RequestBuilder gives you the power to go beyond defaults.
// It is possible to set up headers, timeout, baseURL, proxy, contentType, not to use
// cache, directly disabling timeout (in an explicit way), and setting max idle connections.
// headers := make(http.Header)
// headers.Add("myHeader", "myValue")
//
// var rb = rest.RequestBuilder{
// Headers: headers,
// Timeout: 200 * time.Millisecond,
// BaseURL: "https://baseURL",
// Proxy: "http://myproxy",
// ContentType: rest.JSON,
// DisableCache: false,
// DisableTimeout: false,
// MaxIdleConnsPerHost: 10,
// }
//
// resp := rb.Get("/mypath")
//
// Mockups
//
// When using mockups, all requests will be sent to the mockup server.
// To activate the mockup *environment* you have two ways: using the flag -mock
// go test -mock
//
// Or by programmatically starting the mockup server
// StartMockupServer()
// An example
// myURL := "http://mytest.com/foo"
//
// myHeaders := make(http.Header)
// myHeaders.Add("Hello", "world")
//
// mock := rest.Mock{
// URL: myURL,
// HTTPMethod: http.MethodGet,
// ReqHeaders: myHeaders,
// RespHTTPCode: http.StatusOK,
// RespBody: "foo",
// }
//
// rest.AddMockups(&mock)
//
// v := rest.Get(myURL)
package rest