Improved README.md

Author: lmammino

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 in your microservices architecture.
+
 ## Install
 
 ```
@@ -25,39 +27,62 @@ const Fastify = require('fastify')
 const server = Fastify()
 
 server.register(require('fastify-http-proxy'), {
-  upstream,
-  prefix: '/upstream', // optional
+  'http://my-api.example.com',
+  prefix: '/api', // optional
   http2: false // optional
 })
 
 server.listen(3000)
 ```
 
-For a more complete example, see `example.js`.
+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, {
+  'http://my-api.example.com',
+  prefix: '/api', // optional
+  http2: false // optional
+})
+
+server.register(proxy, {
+  'http://single-signon.example.com/auth',
+  prefix: '/auth', // optional
+  http2: false // optional
+})
+
+server.listen(3000)
+```
+
+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