@bbc/http-transport
Version:
A flexible, modular REST client built for ease-of-use and resilience.
2,584 lines (676 loc) • 30.1 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>HttpTransportClient - Documentation</title>
<script src="scripts/prettify/prettify.js"></script>
<script src="scripts/prettify/lang-css.js"></script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<input type="checkbox" id="nav-trigger" class="nav-trigger" />
<label for="nav-trigger" class="navicon-button x">
<div class="navicon"></div>
</label>
<label for="nav-trigger" class="overlay"></label>
<nav>
<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#redirect">redirect</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>
</nav>
<div id="main">
<h1 class="page-title">HttpTransportClient</h1>
<section>
<header>
<h2>
HttpTransportClient
</h2>
<div class="class-description"><p>Core client</p></div>
</header>
<article>
<div class="container-overview">
<h2>Constructor</h2>
<h4 class="name" id="HttpTransportClient"><span class="type-signature"></span>new HttpTransportClient<span class="signature">(transport, defaults)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line9">line 9</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Create a HttpTransport.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>transport</code></td>
<td class="type">
<span class="param-type">Transport</span>
</td>
<td class="description last"><p>Transport instance.</p></td>
</tr>
<tr>
<td class="name"><code>defaults</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"><p>default configuration</p></td>
</tr>
</tbody>
</table>
</div>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="asBody"><span class="type-signature">(async) </span>asBody<span class="signature">()</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line290">line 290</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Initiates the request, returning the response body, if successful.</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const body = await httpTransport.createClient()
.asBody();
console.log(body);</code></pre>
<h5>Returns:</h5>
<div class="param-desc">
<p>a Promise. If the Promise fulfils,
the fulfilment value is the response body. The body type defaults to string.
If the content-type response header contains 'json'
or the json: true option has been set on transport layer
then the body type will be json.</p>
</div>
<h4 class="name" id="asResponse"><span class="type-signature">(async) </span>asResponse<span class="signature">()</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line309">line 309</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Initiates the request, returning a http transport response object, if successful.</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.asResponse()
console.log(response);</code></pre>
<h5>Returns:</h5>
<div class="param-desc">
<p>a Promise. If the Promise fulfils,
the fulfilment value is response object.</p>
</div>
<h4 class="name" id="delete"><span class="type-signature"></span>delete<span class="signature">(baseUrl)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line112">line 112</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Make a HTTP DELETE request</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.delete(baseUrl)
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>baseUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="get"><span class="type-signature"></span>get<span class="signature">(baseUrl)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line53">line 53</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Make a HTTP GET request</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.get(url)
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>baseUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="head"><span class="type-signature"></span>head<span class="signature">(baseUrl)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line150">line 150</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Make a HTTP HEAD request</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.head(baseUrl)
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>baseUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="headers"><span class="type-signature"></span>headers<span class="signature">(name, value)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line170">line 170</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Sets the request headers</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.headers({
'User-Agent' : 'someUserAgent'
})
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">object</span>
</td>
<td class="description last"><p>header name or headers object</p></td>
</tr>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">object</span>
</td>
<td class="description last"><p>header value</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="patch"><span class="type-signature"></span>patch<span class="signature">(baseUrl, request)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line130">line 130</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Make a HTTP PATCH request</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.put(baseUrl, requestBody)
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>baseUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>request</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"><p>body</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="post"><span class="type-signature"></span>post<span class="signature">(baseUrl, request)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line71">line 71</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Make a HTTP POST request</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.post(baseUrl, requestBody)
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>baseUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>request</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"><p>body</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="put"><span class="type-signature"></span>put<span class="signature">(baseUrl, request)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line92">line 92</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Make a HTTP PUT request</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.put(baseUrl, requestBody)
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>baseUrl</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>request</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"><p>body</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="query"><span class="type-signature"></span>query<span class="signature">(name, value)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line193">line 193</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Sets the query strings</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.query({
'perPage' : 1
})
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">object</span>
</td>
<td class="description last"><p>query name or query object</p></td>
</tr>
<tr>
<td class="name"><code>value</code></td>
<td class="type">
<span class="param-type">string</span>
|
<span class="param-type">object</span>
</td>
<td class="description last"><p>query value</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="redirect"><span class="type-signature"></span>redirect<span class="signature">(redirect)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line233">line 233</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Set the redirect handling:
<code>follow</code> (default) to follow the redirects automatically,
<code>manual</code> to extract redirect headers,
<code>error</code> to reject redirect</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.redirect('manual') // for this request only
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>redirect</code></td>
<td class="type">
<span class="param-type">'follow'</span>
|
<span class="param-type">'manual'</span>
|
<span class="param-type">'error'</span>
</td>
<td class="description last"><p>redirect handling</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="retry"><span class="type-signature"></span>retry<span class="signature">(retries)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line250">line 250</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Set the number of retries on failure for the request</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.retry(5) // for this request only
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>retries</code></td>
<td class="type">
<span class="param-type">integer</span>
</td>
<td class="description last"><p>number of times to retry a failed request</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="retryDelay"><span class="type-signature"></span>retryDelay<span class="signature">(delay)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line268">line 268</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Set the delay between retries in ms</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.retry(2)
.retryDelay(200)
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>delay</code></td>
<td class="type">
<span class="param-type">integer</span>
</td>
<td class="description last"><p>number of ms to wait between retries (default: 100)</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="timeout"><span class="type-signature"></span>timeout<span class="signature">(time)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line213">line 213</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Sets a request timeout</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const httpTransport = require('@bbc/http-transport');
const response = await httpTransport.createClient()
.timeout(1)
.asResponse();</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>time</code></td>
<td class="type">
<span class="param-type">integer</span>
</td>
<td class="description last"><p>timeout in seconds</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
<h4 class="name" id="use"><span class="type-signature"></span>use<span class="signature">(fn)</span><span class="type-signature"></span></h4>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="client.js.html">client.js</a>, <a href="client.js.html#line35">line 35</a>
</li></ul></dd>
</dl>
<div class="description">
<p>Registers a per request plugin</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>const toError = require('@bbc/http-transport-to-error');
const httpTransport = require('@bbc/http-transport');
httpTransport.createClient()
.use(toError(404));</code></pre>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>fn</code></td>
<td class="type">
<span class="param-type">function</span>
</td>
<td class="description last"><p>per request plugin</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>a HttpTransport instance</p>
</div>
</article>
</section>
</div>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.11</a> on Mon Feb 19 2024 16:02:59 GMT+0100 (Central European Standard Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>
<script>prettyPrint();</script>
<script src="scripts/linenumber.js"></script>
</body>
</html>