UNPKG

10.8 kBHTMLView Raw
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 <!--[if lt IE 9]>
10 <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
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.
134The 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');
166const 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/';
170const HttpTransport = require('@bbc/http-transport');
171
172const builder = HttpTransport.createBuilder();
173
174const client = builder
175 .use(toError())
176 .retries(2)
177 .createClient();
178
179const 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/';
232const HttpTransport = require('@bbc/http-transport');
233
234const 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
246const requestTransport = new HttpTransport.RequestTransport(defaultConfig);
247
248const 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