NONRTRIC-1005: ServiceManager README for dynamic URIs

Change-Id: Ib050c5452fa5b39b6382306316de217891fa2da0
Signed-off-by: DenisGNoonan <denis.noonan@est.tech>

diff --git a/servicemanager/README.md b/servicemanager/README.md
index 5f04d2f..c322bae 100644 (file)
--- a/servicemanager/README.md
+++ b/servicemanager/README.md
@@ -145,4 +145,63 @@ The additional env file needs to exist in the sme/servicemanager folder so that
 
 ## Postman
 
-A Postman collection has been included in this repo at sme/postman/ServiceManager.postman_collection.json.
\ No newline at end of file
+A Postman collection has been included in this repo at sme/postman/ServiceManager.postman_collection.json.
+
+## Interface Descriptions
+
+To distinguish between multiple interface descriptions, Service Manager prepends the port number and a hash code to the URL path.
+
+## Static and Dynamic Routes
+
+We can specify either static or dynamic routes. Static routing defines a route when there is a single route for traffic to reach a destination. Dynamic routing allows us to specify path parameters. In this config file, we specify path parameters using regular expressions.
+
+Kong uses the regex definition from the [Rust programming language](https://docs.rs/regex/latest/regex/) to specify the regular expression (regex) that describes the path parameters, [Kong regex](https://docs.konghq.com/gateway/latest/key-concepts/routes/#regular-expressions).
+
+An example of a static path is as follows. This is the straightforward case.
+
+```http
+   /rapps
+```
+
+An example of a dynamic path is
+
+```http
+   ~/rapps/(?<rappId>[a-zA-Z0-9]+([-_][a-zA-Z0-9]+)*)
+```
+
+Our dynamic path starts with a ~ character. In this example, we have a path parameter that is described by a regex capture group called rappId. The regex describes a word made of mixed-case alphanumeric characters optionally followed by one or more sets of a dash or underscore together with another word.
+
+When the Service Manager client calls a dynamic API, we call the URL without the '~'. Kong substitutes the path parameter according to the rules specified in the regex. Therefore, we can call the above example by using
+
+```http
+   /rapps/my-rApp-id
+```
+
+as the URL where my-rApp-id is the rApp id of in the rApp Manager. The name my-rApp-id has to match the regex shown above.
+
+It is required to name the capture group in this YAML config file. The capture group name is used by Service Manager when creating a Kong Request Transformer plugin. We can specify multiple capture groups in a URL if there are multiple path parameters in the API path.
+
+We create a Kong Request Transformer plugin with .data[].config.replace, as in the following example curl with abridged response.
+
+```sh
+curl -X GET http://oran-nonrtric-kong-admin.nonrtric.svc.cluster.local:8001/plugins
+```
+
+```json
+{
+  "body": [],
+  "uri": "/rapps/$(uri_captures[\"rappId\"])",
+  "headers": [],
+  "querystring": []
+}
+```
+
+In our example, this allows Kong to match /rapps/my-rApp-id.
+
+The Service Manager uses the following regex to search and replace the YAML file regexes.
+
+```regex
+/\(\?<([^>]+)>([^\/]+)/
+```
+
+Please note that the example path, /rapps/my-rApp-id, is not terminated by a '/'. Service Manager adds a '/' for internal matching. This made the regex easier to develop. Service Manager will match on /rapps/my-rApp-id/ for this case.