1 | # HttpTransport
|
2 |
|
3 | > A flexible, modular REST client built for ease-of-use and resilience
|
4 |
|
5 | ## Common examples
|
6 |
|
7 | #### Supported HTTP methods
|
8 |
|
9 | Make a HTTP GET request using `.get`
|
10 |
|
11 | ```js
|
12 | const url = 'http://example.com/';
|
13 | const res = await HttpTransport.createClient()
|
14 | .get(url)
|
15 | .asResponse()
|
16 |
|
17 | console.log(res);
|
18 | ```
|
19 |
|
20 | Make a HTTP POST request using `.post`
|
21 |
|
22 | ```js
|
23 | const url = 'http://example.com/';
|
24 | const res = await HttpTransport.createClient()
|
25 | .post(url, requestBody)
|
26 | .asResponse()
|
27 |
|
28 | console.log(res);
|
29 | ```
|
30 |
|
31 | PATCH, DELETE, HEAD are also supported.
|
32 |
|
33 | #### Query strings
|
34 |
|
35 | Make a HTTP GET request specifying query strings using `.query`
|
36 |
|
37 | Single query string
|
38 | ```js
|
39 | const url = 'http://example.com/';
|
40 | const res = await HttpTransport.createClient()
|
41 | .get(url)
|
42 | .query('example', 'true')
|
43 | .asResponse();
|
44 |
|
45 | console.log(res);
|
46 | ```
|
47 |
|
48 | Multiple query strings:
|
49 | ```js
|
50 | const url = 'http://example.com/';
|
51 | const res = await HttpTransport.createClient()
|
52 | .get(url)
|
53 | .query({
|
54 | example1: true
|
55 | example2: false
|
56 | })
|
57 | .asResponse();
|
58 |
|
59 | console.log(res);
|
60 | ```
|
61 |
|
62 |
|
63 | #### Headers
|
64 |
|
65 | Make a HTTP GET request specifying request headers using `.headers`
|
66 |
|
67 | Add a single header:
|
68 | ```js
|
69 | const res = await HttpTransport.createClient()
|
70 | .get(url)
|
71 | .headers('someHeader1', 'someValue1')
|
72 | .asResponse();
|
73 |
|
74 | console.log(res);
|
75 | ```
|
76 |
|
77 | Add multiple headers:
|
78 | ```js
|
79 | const res = await HttpTransport.createClient()
|
80 | .get(url)
|
81 | .headers({
|
82 | 'someHeader1' : 'someValue1'
|
83 | 'someHeader2' : 'someValue2'
|
84 | })
|
85 | .asResponse();
|
86 |
|
87 | console.log(res);
|
88 | ```
|
89 |
|
90 | #### Handling errors
|
91 |
|
92 | Convert `Internal Server` responses (500) to errors:
|
93 |
|
94 | ```js
|
95 | const toError = require('@bbc/http-transport-to-error');
|
96 |
|
97 | const url = 'http://example.com/';
|
98 | const client = HttpTransport.createBuilder()
|
99 | .use(toError())
|
100 | .createClient(); // for all requests
|
101 |
|
102 | try {
|
103 | await client.get(url)
|
104 | .asResponse();
|
105 | } catch (err) {
|
106 | console.error(err);
|
107 | }
|
108 | ```
|
109 |
|
110 | `toError` is **only** required if the underlying client does not support HTTP error conversion.
|
111 | The default transport is `node-fetch`, which does **not** convert errors.
|
112 |
|
113 | #### Retries
|
114 |
|
115 | Make a HTTP GET and retry twice on error `.retry`
|
116 |
|
117 | ```js
|
118 | const toError = require('@bbc/http-transport-to-error');
|
119 |
|
120 | const client = HttpTransport.createBuilder()
|
121 | .use(toError())
|
122 | .createClient();
|
123 |
|
124 | const res = await client.get('http://example.com/')
|
125 | .retry(2)
|
126 | .asResponse();
|
127 |
|
128 | console.log(res);
|
129 | ```
|
130 |
|
131 | #### Timeouts
|
132 |
|
133 | Make a HTTP GET and timeout after 50ms `.query`
|
134 |
|
135 | ```js
|
136 | const body = await HttpTransport.createClient()
|
137 | .get(url)
|
138 | .timeout(50)
|
139 | .asBody();
|
140 | ```
|
141 |
|
142 | #### Using the Client buider
|
143 |
|
144 | The builder can be used to define behavior for **all requests**. This includes:
|
145 | * Default retries
|
146 | * Default retry delay
|
147 | * Default user agent
|
148 | * Middleware
|
149 |
|
150 | The builder is instantiated via `.createBuilder`:
|
151 | ```js
|
152 | const HttpTransport = require('@bbc/http-transport');
|
153 | const builder = HttpTransport.createBuilder();
|
154 | ```
|
155 |
|
156 | `createClient` instantiates a configured transport client:
|
157 | ```js
|
158 | const url = 'http://example.com/';
|
159 | const HttpTransport = require('@bbc/http-transport');
|
160 |
|
161 | const builder = HttpTransport.createBuilder();
|
162 |
|
163 | const client = builder
|
164 | .use(toError())
|
165 | .retries(2)
|
166 | .createClient();
|
167 |
|
168 | const body = await client.get(url).asBody();
|
169 | ```
|
170 |
|
171 | #### Middleware
|
172 |
|
173 | Middleware are functions that can be executed with before and after a request. Middleware is typically used to:
|
174 |
|
175 | * Modify the request object e.g set headers
|
176 | * Terminate a request early e.g for caching purposes
|
177 | * Modify the response object e.g format the response body
|
178 |
|
179 | Middleware can be executed **per request** using the `.use` method:
|
180 | ```js
|
181 | const exampleMiddleware = require('exampleMiddleware');
|
182 |
|
183 | const url = 'http://example.com/';
|
184 | const client = HttpTransport.createClient();
|
185 |
|
186 | try {
|
187 | await client
|
188 | .use(exampleMiddleware()) // only for this request
|
189 | .get(url)
|
190 | .asResponse();
|
191 | } catch (err) {
|
192 | console.error(err);
|
193 | }
|
194 | ```
|
195 |
|
196 | Middleware can also be executed **for every request** using the `.use` of the client builder. The client builder is created using the `createBuilder` method:
|
197 |
|
198 | ```js
|
199 | const exampleMiddleware = require('exampleMiddleware');
|
200 |
|
201 | const url = 'http://example.com/';
|
202 | const client = HttpTransport.createBuilder()
|
203 | .use(exampleMiddleware()) // for all requests
|
204 | .createClient();
|
205 |
|
206 | try {
|
207 | await client
|
208 | .get(url)
|
209 | .asResponse();
|
210 | } catch (err) {
|
211 | console.error(err);
|
212 | }
|
213 | ```
|
214 |
|
215 | For writing middleware, see the [offical guide](https://github.com/koajs/koa/blob/master/docs/guide.md)
|
216 |
|
217 | #### Official HttpTransport middleware
|
218 | See [Caching](https://github.com/bbc/http-transport-cache)
|
219 |
|
220 | See [Collapsing](https://github.com/bbc/http-transport-request-collapse)
|
221 |
|
222 | See [Errors](https://github.com/bbc/http-transport-to-error)
|
223 |
|
224 | See [Stats](https://github.com/bbc/http-transport-statsd)
|
225 |
|
226 | See [Ratelimiting](https://github.com/bbc/http-transport-rate-limiter)
|
227 |
|
228 | See [xray](https://github.com/bbc/http-transport-xray)
|
229 |
|
230 | #### Callback support
|
231 | HttpTransport does not support callbacks. However, to integrate with legacy code, use the [callback adapter](https://github.com/bbc/http-transport-callbacks)
|
232 |
|
233 | #### Setting default behaviour of underlying http transport
|
234 |
|
235 | Make a HTTP GET request by passing default configuration to RequestTransport, and supplying the configured RequestTransport to `.createClient`
|
236 |
|
237 | ```js
|
238 | const url = 'http://example.com/';
|
239 | const HttpTransport = require('@bbc/http-transport');
|
240 |
|
241 | const defaultConfig = {
|
242 | agentOpts: { // Here you can pass in any options for the https agent https://nodejs.org/api/https.html#class-httpsagent
|
243 | keepAlive: true,
|
244 | maxSockets: 1000
|
245 | },
|
246 | defaults: {
|
247 | json: true, // parses the response body as json
|
248 | timeout: 2000 // sets timeout for each request
|
249 | compress: true // support gzip/deflate content encoding. false to disable
|
250 | proxy: 'http://someproxyurl.co.uk'
|
251 | }
|
252 | };
|
253 |
|
254 | const requestTransport = new HttpTransport.RequestTransport(defaultConfig);
|
255 |
|
256 | const res = await HttpTransport.createClient(requestTransport);
|
257 | .get(url)
|
258 | .asResponse();
|
259 |
|
260 | if (res.statusCode === 200) {
|
261 | console.log(res.body);
|
262 | }
|
263 | ``` |
\ | No newline at end of file |