This is a simple middleware utility that can be used to proxy JSON requests for Express node.js servers. This is most useful when you want to simply pass a response from a service to a client, without needing to buffer or modify it. For example, your server could do an authentication check, and then simply stream the data from the service to the client.
Assuming you have an express Router, here's a quick way to get things wired up:
;;const router = ;router;;
In the example above, let's break down what happened in our router:
- We have some middleware that first checked if a user was loggedIn, assuming they are with whatever auth your app is using, we let them through.
- We created a
RequestHandler, and pointed it to
https://my.service.url, and attached some custom HTTP headers for the service.
- We also provided an error handler, which we can use to inform our clients of the error how our application best sees fit. This is different from the service responding with an error, in which case that would have just been proxied through as well.
json-proxy-middleware is designed to be fairly flexible, yet performant for
configuring how & where you proxy requests through your node.js middletier.
The quick start above includes the barebones to get you up and running. Below
is the full API with some details on how to use the middleware in a variety
of different scenarios.
There is a single, default export from the utility, and that is the middleware itself:
It takes a single
ProxyMiddlewareOptions object, and returns a
||a message that will be appended to proxy start/end/error logging|
||an object or function that returns an object with additional headers to forward on the proxied request|
||logger instance (optional)||any valid logger instance with methods
||attaches a curlCommand to your request headers for easier debugging (defaults to false)|
||a string or function that returns a string indicating a host to have a request proxied to|
When a logger is provided, this message will be appended to to info/error logs and can be used to customize the log messages per jsonProxy usage as needed.
When provided, these will be appended to the default headers that we forward. By default we provide the headers necessary for JSON requests:
Accept: "application/json""Content-Type": "application/json"
If you'd like, you can provide an object with static headers to forward, like so:
In some cases, you need to also forward request headers that came in from the client, or you might need to forward headers based on the request itself. In that case, you can provide a function that the middleware will call for each incoming proxy request:
Setting headers this way allows you to perform a white or black list style header forwarding for the proxy as well.
When a logger is provided,
json-proxy-middleware will log out information useful
for debugging, such as when a proxy request started, when it ended, and how long it
took. We also log out errors in the event those occur. You can provide any kind of
logger you prefer, as long as it has a
.error() log level method to
It's often useful to debug a request using a curl command. You will see this in
your response headers as
headers['x-curl-command']. You can set this option
as a boolean:
Or set it conditionally:
urlHost is combined with the path on the proxy to perform a request. It is
required, and you can provide either a
function that returns a string
for the request. The simplest example looks like this:
This will result in
jsonProxy making a
GET request to:
Because of the way Express are designed with their routing, you can also leverage this with regex / glob paths, like so:
This will mean that
json-proxy-middleware will proxy any paths that match.
It's a great idea to understand if this will open up security holes in your
service, and in general proxying requests through globs requires some thought &
coordination with the proxied service.
Another thing to note with Express servers, is that you can mount routes at
different base paths.
json-proxy-middleware by default navigates this for you,
so keep that in mind when using proxy routers in scenarios like this:
;const server = ;const router = express;router;server;
In this case, your clients will be making requests to
json-proxy-middleware will be proxying requests to
https://my.service.url/service/REST/v1/**, removing the
/api portion from the