Improved README.md

README.md

@@ -12,6 +12,8 @@ received with a given prefix (or none) to an upstream. All Fastify hooks are sti
 [`fastify-reply-from`](http://npm.im/fastify-reply-from), which enables
 you for single route proxying.
 
+This plugin can be used in a variety of circumstances, for example if you have to proxy an internal domain to an external domain (useful to avoid CORS problems) or to implement your own API gateway for a microservices architecture.
+
 ## Install
 
 ```
@@ -25,39 +27,64 @@ const Fastify = require('fastify')
 const server = Fastify()
 
 server.register(require('fastify-http-proxy'), {
-  upstream,
-  prefix: '/upstream', // optional
+  upstream: 'http://my-api.example.com',
+  prefix: '/api', // optional
+  http2: false // optional
+})
+
+server.listen(3000)
+```
+
+This will proxy any request starting with `/api` to `http://my-api.example.com`. For instance `http://localhost:3000/api/users` will be proxied to `http://my-api.example.com/users`.
+
+If you want to have different proxies on different prefixes in you can register multiple instances of the plugin as shown in the following snippet:
+
+```js
+const Fastify = require('fastify')
+const server = Fastify()
+const proxy = require('fastify-http-proxy')
+
+server.register(proxy, {
+  upstream: 'http://my-api.example.com',
+  prefix: '/api', // optional
+  http2: false // optional
+})
+
+server.register(proxy, {
+  upstream: 'http://single-signon.example.com/auth',
+  prefix: '/auth', // optional
   http2: false // optional
 })
 
 server.listen(3000)
 ```
 
-For a more complete example, see `example.js`.
+Notice that in this case it is important to use the `prefix` option to tell the proxy how to properly route the requests across different upstreams.
+
+For other examples, see `example.js`.
 
 ## Options
 
 This `fastify` plugin supports the following options.
-Note that this plugin is fully encapsulated, and non-JSON payloads will
-be streamed directly to the destination.
+
+*Note that this plugin is fully encapsulated, and non-JSON payloads will
+be streamed directly to the destination.*
 
 ### upstream
 
-The target server to use for proxying
+An URL (including protocol) that represents the target server to use for proxying.
 
 ### prefix
 
-The prefix to mount this plugin on. This is provided by fastify itself.
+The prefix to mount this plugin on. All the requests to the current server starting with the given prefix will be proxied to the provided upstream.
 
 ### beforeHandler
 
-A `beforeHandler` to be applied on all routes. Useful for performing
-authentication.
+A `beforeHandler` to be applied on all routes. Useful for performing actions before the proxy is executed (e.g. check for authentication).
 
 ### http2
 
-A `beforeHandler` to be applied on all routes. Useful for performing
-authentication.
+A boolean value that indicates whether the proxy should support http2.
 
 ## Benchmarks