Adjusted routing.rst (while learning) (ThreeMammals#504)

docs/features/routing.rst

@@ -1,8 +1,8 @@
 Routing
 =======
 
-Ocelot's primary functionality is to take incomeing http requests and forward them on
-to a downstream service. At the moment in the form of another http request (in the future
+Ocelot's primary functionality is to take incoming http requests and forward them on
+to a downstream service. Ocelot currently only supports this in the form of another http request (in the future
 this could be any transport mechanism). 
 
 Ocelot's describes the routing of one request to another as a ReRoute. In order to get 
@@ -15,8 +15,7 @@ anything working in Ocelot you need to set up a ReRoute in the configuration.
         ]
     }
 
-In order to set up a ReRoute you need to add one to the json array called ReRoutes like
-the following.
+To configure a ReRoute you need to add one to the ReRoutes json array.
 
 .. code-block:: json
 
@@ -33,16 +32,16 @@ the following.
         "UpstreamHttpMethod": [ "Put", "Delete" ]
     }
 
-The DownstreamPathTemplate, Scheme and DownstreamHostAndPorts make the URL that this request will be forwarded to. 
+The DownstreamPathTemplate, DownstreamScheme and DownstreamHostAndPorts define the URL that a request will be forwarded to. 
 
-DownstreamHostAndPorts is an array that contains the host and port of any downstream services that you wish to forward requests to. Usually this will just contain one entry but sometimes you might want to load balance
-requests to your downstream services and Ocelot let's you add more than one entry and then select a load balancer.
+DownstreamHostAndPorts is a collection that defines the host and port of any downstream services that you wish to forward requests to. 
+Usually this will just contain a single entry but sometimes you might want to load balance requests to your downstream services and Ocelot allows you add more than one entry and then select a load balancer.
 
-The UpstreamPathTemplate is the URL that Ocelot will use to identity which DownstreamPathTemplate to use for a given request. Finally the UpstreamHttpMethod is used so
-Ocelot can distinguish between requests to the same URL and is obviously needed to work :)
+The UpstreamPathTemplate is the URL that Ocelot will use to identity which DownstreamPathTemplate to use for a given request. 
+The UpstreamHttpMethod is used so Ocelot can distinguish between requests with different HTTP verbs to the same URL. You can set a specific list of HTTP Methods or set an empty list to allow any of them. 
 
-You can set a specific list of HTTP Methods or set an empty list to allow any of them. In Ocelot you can add placeholders for variables to your Templates in the form of {something}.
-The placeholder needs to be in both the DownstreamPathTemplate and UpstreamPathTemplate. If it is Ocelot will attempt to replace the placeholder with the correct variable value from the Upstream URL when the request comes in.
+In Ocelot you can add placeholders for variables to your Templates in the form of {something}.
+The placeholder variable needs to be present in both the DownstreamPathTemplate and UpstreamPathTemplate properties. When it is Ocelot will attempt to substitute the value in the UpstreamPathTemplate placeholder into the DownstreamPathTemplate for each request Ocelot processes.
 
 You can also do a catch all type of ReRoute e.g. 
 
@@ -63,21 +62,24 @@ You can also do a catch all type of ReRoute e.g.
 
 This will forward any path + query string combinations to the downstream service after the path /api.
 
-At the moment without any configuration Ocelot will default to all ReRoutes being case insensitive.
+
+The default ReRouting configuration is case insensitive!
+
 In order to change this you can specify on a per ReRoute basis the following setting.
 
 .. code-block:: json
 
     "ReRouteIsCaseSensitive": true
 
 This means that when Ocelot tries to match the incoming upstream url with an upstream template the
-evaluation will be case sensitive. This setting defaults to false so only set it if you want 
-the ReRoute to be case sensitive is my advice!
+evaluation will be case sensitive. 
 
 Catch All
 ^^^^^^^^^
 
-Ocelot's routing also supports a catch all style routing where the user can specify that they want to match all traffic if you set up your config like below the request will be proxied straight through (it doesnt have to be url any placeholder name will work). 
+Ocelot's routing also supports a catch all style routing where the user can specify that they want to match all traffic.
+
+If you set up your config like below, all requests will be proxied straight through. The placeholder {url} name is not significant, any name will work.
 
 .. code-block:: json
 
@@ -136,18 +138,15 @@ In order to use this feature please add the following to your config.
 
 The ReRoute above will only be matched when the host header value is somedomain.com.
 
-If you do not set UpstreamHost on a ReRoue then any host header can match it. This is basically a catch all and 
-preservers existing functionality at the time of building the feature. This means that if you have two ReRoutes that are the same apart from the UpstreamHost where one is null and the other set. Ocelot will favour the one that has been set. 
+If you do not set UpstreamHost on a ReRoute then any host header will match it. This means that if you have two ReRoutes that are the same, apart from the UpstreamHost, where one is null and the other set Ocelot will favour the one that has been set. 
 
 This feature was requested as part of `Issue 216 <https://github.com/TomPallister/Ocelot/pull/216>`_ .
 
 Priority
 ^^^^^^^^
 
-In `Issue 270 <https://github.com/TomPallister/Ocelot/pull/270>`_ I finally decided to expose the ReRoute priority in 
-ocelot.json. This means you can decide in what order you want your ReRoutes to match the Upstream HttpRequest.
-
-In order to get this working add the following to a ReRoute in ocelot.json, 0 is just an example value here but will explain below.
+You can define the order you want your ReRoutes to match the Upstream HttpRequest by including a "Priority" property in ocelot.json
+See `Issue 270 <https://github.com/TomPallister/Ocelot/pull/270>`_ for reference
 
 .. code-block:: json
 
@@ -182,14 +181,15 @@ matched /goods/{catchAll} (because this is the first ReRoute in the list!).
 Dynamic Routing
 ^^^^^^^^^^^^^^^
 
-This feature was requested in `issue 340 <https://github.com/TomPallister/Ocelot/issue/340>`_. The idea is to enable dynamic routing 
-when using a service discovery provider so you don't have to provide the ReRoute config. See the docs :ref:`service-discovery` if 
+This feature was requested in `issue 340 <https://github.com/TomPallister/Ocelot/issue/340>`_. 
+
+The idea is to enable dynamic routing when using a service discovery provider so you don't have to provide the ReRoute config. See the docs :ref:`service-discovery` if 
 this sounds interesting to you.
 
 Query Strings
 ^^^^^^^^^^^^^
 
-Ocelot allow's you to specify a querystring as part of the DownstreamPathTemplate like the example below.
+Ocelot allows you to specify a querystring as part of the DownstreamPathTemplate like the example below.
 
 .. code-block:: json
 
@@ -217,7 +217,7 @@ Ocelot allow's you to specify a querystring as part of the DownstreamPathTemplat
 
 In this example Ocelot will use the value from the {unitId} in the upstream path template and add it to the downstream request as a query string parameter called unitId!
 
-Ocelot will also allow you to put query string parametrs in the UpstreamPathTemplate so you can match certain queries to certain services.
+Ocelot will also allow you to put query string parameters in the UpstreamPathTemplate so you can match certain queries to certain services.
 
 .. code-block:: json
 
@@ -244,4 +244,4 @@ Ocelot will also allow you to put query string parametrs in the UpstreamPathTemp
     }
 
 In this example Ocelot will only match requests that have a matching url path and the querystring starts with unitId=something. You can have other queries after this
-but you must start with the matching parameter. Also in this example Ocelot will swap the unitId param from the query string and use it in the downstream request path. 
+but you must start with the matching parameter. Also Ocelot will swap the {unitId} parameter from the query string and use it in the downstream request path.