Skip to main content
Version: 3.10.0

Proxy variants

Variants of type proxy allow to proxy the request to another host and pass response back. They also make able to modify the request before sending it to the other host, or to modify the response before sending it to the client.

caution

Due to backward compatibility reasons, the current proxy variant which is recommended to use is named proxy-v4. All docs and examples in this page are only valid when using the type proxy-v4. In the next major version the proxy-v4 variant will replace the proxy one, which currently is legacy.

Options

The options property in a variant of type proxy-v4 must be an object containing next properties:

info

A variant of type proxy-v4 uses the express-http-proxy package under the hood, and it supports all of its options.

Examples

Here you have some examples in which the usage of the proxy variant type might be useful.

Proxy requests of one route

The next example shows how to proxy GET requests to the /api/users url to http://127.0.0.1:8080/api/users

module.exports = [
{
id: "users",
url: "/api/users",
method: "GET",
variants: [
{
id: "real-api",
type: "proxy-v4", // Variant of type "proxy-v4"
options: {
host: "http://127.0.0.1:8080", // proxy host
},
},
],
},
];

Proxy all requests with a delay

You could use a proxy variant to proxy a whole API path (or even the whole API) to a host, and set a delay time for the responses. So you can slow down the real API responses:

module.exports = [
{
id: "books",
url: "/api/books/*",
delay: 1000, // Delay
method: "GET",
variants: [
{
id: "proxied",
type: "proxy-v4", // Variant of type "proxy-v4"
options: {
host: "http://127.0.0.1:8080", // proxy host
},
},
],
},
];

Proxy as a fallback

Adding a route to the end of a collection would produce the route being used if no other previous route matches the url and method. So, you could simulate only some routes and add a fallback to the real API for the routes that were not specifically defined.

module.exports = [
{
id: "get-users",
url: "/api/users", // Handle GET requests to "/api/users"
method: "GET",
variants: [
{
id: "one",
type: "json",
options: {
status: 200,
body: [ // body to send
{
"id": 1,
"name": "John Doe"
},
]
}
},
],
},
{
id: "proxy-all", // Proxy all requests
url: "*",
method: ["GET", "POST", "PATCH", "PUT"],
variants: [
{
id: "real-api",
type: "proxy-v4", // This route variant will use the "proxy-v4" handler
options: {
host: "http://127.0.0.1:8080", // proxy host
},
},
],
},
];

Now you should define the collection as in:

[
{
"id": "proxy-fallback",
"routes": ["get-users:one", "proxy-all:real-api"]
},
]
note

In this example, every request except the /api/users one will be proxied to http://127.0.0.1:8080

tip

For further information about how to define collections, please read the collections chapter.

Modifying the host response

You can use the express-http-proxy userResDecorator option to intercept the response from the host and modify it:

module.exports = [
{
id: "get-user",
url: "/api/users/:id",
method: "GET",
variants: [
{
id: "add-prefix",
type: "proxy-v4",
options: {
host: "http://127.0.0.1:8080",
options: {
userResDecorator: function(proxyRes, proxyResData, userReq, userRes) {
data = JSON.parse(proxyResData.toString('utf8'));
data.name = `Modified ${data.name}`;
return JSON.stringify(data);
}
},
},
},
],
},
];
note

This example will proxy the requests to /api/users/:id, and it will add the "Modified " prefix to the user name.

Modifying the request

You can use the express-http-proxy proxyReqOptDecorator option to intercept the request before it is sent to the host and modify it:

module.exports = [
{
id: "get-user",
url: "/api/users/:id",
method: "GET",
variants: [
{
id: "real-api",
type: "proxy-v4",
options: {
host: "http://127.0.0.1:8080",
options: {
proxyReqOptDecorator: function(proxyReqOpts, srcReq) {
// you can update headers
proxyReqOpts.headers['Content-Type'] = 'text/html';
// you can change the method
proxyReqOpts.method = 'GET';
return proxyReqOpts;
}
},
},
},
],
},
];
note

Note: The req.path cannot be changed via this method. Use the proxyReqPathResolver instead. Read the express-http-proxy docs to check all available options.