@bbc/http-transport
Version:
A flexible, modular REST client built for ease-of-use and resilience.
282 lines (227 loc) • 11.2 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>Home - 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">
<section class="readme">
<article><h1>HttpTransport</h1>
<blockquote>
<p>A flexible, modular REST client built for ease-of-use and resilience</p>
</blockquote>
<h2>Common examples</h2>
<h4>Supported HTTP methods</h4>
<p>Make a HTTP GET request using <code>.get</code></p>
<pre class="prettyprint source lang-js"><code> const url = 'http://example.com/';
const res = await HttpTransport.createClient()
.get(url)
.asResponse()
console.log(res);
</code></pre>
<p>Make a HTTP POST request using <code>.post</code></p>
<pre class="prettyprint source lang-js"><code> const url = 'http://example.com/';
const res = await HttpTransport.createClient()
.post(url, requestBody)
.asResponse()
console.log(res);
</code></pre>
<p>PATCH, DELETE, HEAD are also supported.</p>
<h4>Query strings</h4>
<p>Make a HTTP GET request specifying query strings using <code>.query</code></p>
<p>Single query string</p>
<pre class="prettyprint source lang-js"><code> const url = 'http://example.com/';
const res = await HttpTransport.createClient()
.get(url)
.query('example', 'true')
.asResponse();
console.log(res);
</code></pre>
<p>Multiple query strings:</p>
<pre class="prettyprint source lang-js"><code> const url = 'http://example.com/';
const res = await HttpTransport.createClient()
.get(url)
.query({
example1: true
example2: false
})
.asResponse();
console.log(res);
</code></pre>
<h4>Headers</h4>
<p>Make a HTTP GET request specifying request headers using <code>.headers</code></p>
<p>Add a single header:</p>
<pre class="prettyprint source lang-js"><code> const res = await HttpTransport.createClient()
.get(url)
.headers('someHeader1', 'someValue1')
.asResponse();
console.log(res);
</code></pre>
<p>Add multiple headers:</p>
<pre class="prettyprint source lang-js"><code> const res = await HttpTransport.createClient()
.get(url)
.headers({
'someHeader1' : 'someValue1'
'someHeader2' : 'someValue2'
})
.asResponse();
console.log(res);
</code></pre>
<h4>Handling errors</h4>
<p>Convert <code>Internal Server</code> responses (500) to errors:</p>
<pre class="prettyprint source lang-js"><code> const toError = require('@bbc/http-transport-to-error');
const url = 'http://example.com/';
const client = HttpTransport.createBuilder()
.use(toError())
.createClient(); // for all requests
try {
await client.get(url)
.asResponse();
} catch (err) {
console.error(err);
}
</code></pre>
<p><code>toError</code> is <strong>only</strong> required if the underlying client does not support HTTP error conversion.
The default transport is <code>node-fetch</code>, which does <strong>not</strong> convert errors.</p>
<h4>Handling redirects</h4>
<p>Set the redirect handling to manual</p>
<pre class="prettyprint source lang-js"><code>const body = await HttpTransport.createClient()
.redirect('manual')
.get(url)
.asBody();
</code></pre>
<h4>Retries</h4>
<p>Make a HTTP GET and retry twice on error <code>.retry</code></p>
<pre class="prettyprint source lang-js"><code> const toError = require('@bbc/http-transport-to-error');
const client = HttpTransport.createBuilder()
.use(toError())
.createClient();
const res = await client.get('http://example.com/')
.retry(2)
.asResponse();
console.log(res);
</code></pre>
<h4>Timeouts</h4>
<p>Make a HTTP GET and timeout after 50ms <code>.query</code></p>
<pre class="prettyprint source lang-js"><code>const body = await HttpTransport.createClient()
.get(url)
.timeout(50)
.asBody();
</code></pre>
<h4>Using the Client buider</h4>
<p>The builder can be used to define behavior for <strong>all requests</strong>. This includes:</p>
<ul>
<li>Default retries</li>
<li>Default retry delay</li>
<li>Default user agent</li>
<li>Middleware</li>
</ul>
<p>The builder is instantiated via <code>.createBuilder</code>:</p>
<pre class="prettyprint source lang-js"><code>const HttpTransport = require('@bbc/http-transport');
const builder = HttpTransport.createBuilder();
</code></pre>
<p><code>createClient</code> instantiates a configured transport client:</p>
<pre class="prettyprint source lang-js"><code>const url = 'http://example.com/';
const HttpTransport = require('@bbc/http-transport');
const builder = HttpTransport.createBuilder();
const client = builder
.use(toError())
.retries(2)
.createClient();
const body = await client.get(url).asBody();
</code></pre>
<h4>Middleware</h4>
<p>Middleware are functions that can be executed with before and after a request. Middleware is typically used to:</p>
<ul>
<li>Modify the request object e.g set headers</li>
<li>Terminate a request early e.g for caching purposes</li>
<li>Modify the response object e.g format the response body</li>
</ul>
<p>Middleware can be executed <strong>per request</strong> using the <code>.use</code> method:</p>
<pre class="prettyprint source lang-js"><code> const exampleMiddleware = require('exampleMiddleware');
const url = 'http://example.com/';
const client = HttpTransport.createClient();
try {
await client
.use(exampleMiddleware()) // only for this request
.get(url)
.asResponse();
} catch (err) {
console.error(err);
}
</code></pre>
<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>
<pre class="prettyprint source lang-js"><code> const exampleMiddleware = require('exampleMiddleware');
const url = 'http://example.com/';
const client = HttpTransport.createBuilder()
.use(exampleMiddleware()) // for all requests
.createClient();
try {
await client
.get(url)
.asResponse();
} catch (err) {
console.error(err);
}
</code></pre>
<p>For writing middleware, see the <a href="https://github.com/koajs/koa/blob/master/docs/guide.md">offical guide</a></p>
<h4>Official HttpTransport middleware</h4>
<p>See <a href="https://github.com/bbc/http-transport-cache">Caching</a></p>
<p>See <a href="https://github.com/bbc/http-transport-request-collapse">Collapsing</a></p>
<p>See <a href="https://github.com/bbc/http-transport-to-error">Errors</a></p>
<p>See <a href="https://github.com/bbc/http-transport-statsd">Stats</a></p>
<p>See <a href="https://github.com/bbc/http-transport-rate-limiter">Ratelimiting</a></p>
<p>See <a href="https://github.com/bbc/http-transport-xray">xray</a></p>
<h4>Callback support</h4>
<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>
<h4>Setting default behaviour of underlying http transport</h4>
<p>Make a HTTP GET request by passing default configuration to RequestTransport, and supplying the configured RequestTransport to <code>.createClient</code></p>
<pre class="prettyprint source lang-js"><code>const url = 'http://example.com/';
const HttpTransport = require('@bbc/http-transport');
const defaultConfig = {
agentOpts: { // Here you can pass in any options for the https agent https://nodejs.org/api/https.html#class-httpsagent
keepAlive: true,
maxSockets: 1000
},
defaults: {
json: true, // parses the response body as json
timeout: 2000 // sets timeout for each request
compress: true // support gzip/deflate content encoding. false to disable
proxy: 'http://someproxyurl.co.uk'
}
};
const requestTransport = new HttpTransport.RequestTransport(defaultConfig);
const res = await HttpTransport.createClient(requestTransport);
.get(url)
.asResponse();
if (res.statusCode === 200) {
console.log(res.body);
}
</code></pre></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>