Update documentation for HTTP path parameters

Author: jthomas

README.md

@@ -713,6 +713,28 @@ Date: Mon, 19 Dec 2016 15:47:53 GMT
 
 Functions exposed through the API Gateway service are automatically converted into Web Actions during deployment. The framework [secures Web Actions for HTTP endpoints](https://github.com/apache/incubator-openwhisk/blob/master/docs/webactions.md#securing-web-actions) using the `require-whisk-auth` annotation. If the `require-whisk-auth` annotation is manually configured, the existing annotation value is used, otherwise a random token is automatically generated.
 
+### URL Path Parameters
+
+The API Gateway service [supports path parameters]() in user-defined HTTP paths. This allows functions to handle URL paths which include templated values, like resource identifiers.
+
+Path parameters are identified using the `{param_name}` format in the URL path. The API Gateway sends the full matched path value in the `__ow_path` field of the event parameters.
+
+```yaml
+functions:
+  retrieve_users:
+    handler: users.get
+    events:
+      - http:
+          method: GET
+          path: /users/{id}
+          resp: http
+```
+
+This feature comes with the following restrictions:
+
+- *Path parameters are only supported when `resp` is configured as`http`.*
+- *Individual path parameter values are not included as separate event parameters. Users have to manually parse values from the full `__ow_path` value.*
+
 ## Exporting Web Actions
 
 Functions can be turned into "*web actions*" which return HTTP content without use of an API Gateway. This feature is enabled by setting an annotation (`web-export`) in the configuration file.