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