[docu-2457] Router Reference, Router Route creation (#4251)

* router reference

* Check

* Add Router doc and reference doc

* vale

* Apply suggestions from code review

Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

* suggestions from code review

Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>

app/_data/docs_nav_gateway_3.0.x.yml

@@ -25,6 +25,8 @@ items:
                 url: /understanding-kong/how-to/request-transformations
               - text: Securing the Database with AWS Secrets Manager
                 url: /understanding-kong/how-to/aws-secrets-manager
+              - text: Configure Routes with Expressions
+                url: /understanding-kong/how-to/router-atc
           - text: Key Concepts
             items:
               - text: Services
@@ -561,3 +563,5 @@ items:
         url: /reference/rate-limit
       - text: Performance Testing Framework Reference
         url: /reference/performance-testing-framework
+      - text: Router Operators
+        url: /reference/router-operators

src/gateway/get-started/configure-services-and-routes.md

@@ -149,11 +149,26 @@ The response body displays the updated change:
 You can configure a route to point to an active service. The router helps {{site.base_gateway}} forward requests to upstream services. Now, you will configure the `/mock` route for the `example_service` service. This route has a specific path that users will use to send requests. 
 A route is configured by sending a **POST** request to the [route object](/gateway/latest/admin-api/#route-object):
 
+{% if_version eq:3.0.x %}
 ```sh
 curl -i -X POST http://localhost:8001/services/example_service/routes \
   --data 'paths[]=/mock' \
   --data name=mocking
 ```
+{% endif_version %}
+
+
+{% if_version gte:3.1.x %}
+```sh
+curl --request POST \
+  --url http://localhost:8001/services/example-service/routes \
+  --header 'Content-Type: multipart/form-data' \
+  --form 'atc=http.path == "/mock"'
+  --data name=mocking
+```
+{% endif_version %}
+
+
 
 If the route was successfully created, the API returns a `201` response code and a response body like this:
 

src/gateway/reference/router-operators.md

@@ -0,0 +1,66 @@
+---
+title: Router Operator Reference for Kong Gateway
+content-type: reference
+---
+
+With the release of version 3.0, {{site.base_gateway}} now ships with a new router. The new router can describe routes using a domain-specific language called Expressions. Expressions can describe routes or paths as patterns using regular expressions. This document serves as a reference for all of the available operators. If you want to learn how to configure routes using Expressions read [How to configure routes using Expressions](gateway/latest/understanding-kong/how-to/router-atc/).
+
+
+## Available fields
+
+| Field | Description |
+| --- | ----------- | 
+| `net.protocol` | The protocol used to communicate with the upstream application.  |
+| `tls.sni`  | Server name indication. | 
+| `http.method` | HTTP methods that match a route. |
+| `http.host`  | Lists of domains that match a route. | 
+| `http.path` | Returns or sets the path. | 
+| `http.raw_path` | Returns or sets the escaped path. | 
+| `http.headers.*` |  Lists of values that are expected in the header of a request. | 
+
+## String
+
+| Operator | Name | Return Type | 
+| --- | ----------- | --- | 
+| == | Equals | Boolean|
+| != | Not equals | Boolean|
+| ~ | Regex matching | Boolean|
+| ^= | Prefix matching | Boolean|
+| =^ | Suffix matching | Boolean|
+| in | Contains | Boolean|
+| not in | Does not contain | Boolean|
+| lower() | Lowercase | String|
+
+## Integer
+
+| Operator | Name | Return Type | 
+| --- | ----------- | --- | 
+| == | Equals | Boolean|
+| != | Not equals| Boolean|
+| > | Greater than | Boolean|
+| >= | Greater than or equal | Boolean|
+| < | Less than | Boolean|
+| <= | Less than or equal | Boolean|
+
+## IP 
+
+| Operator | Name | Return Type | 
+| --- | ----------- | --- | 
+| == | Equals | Boolean|
+| != | Not equals | Boolean|
+| in | Contains | Boolean|
+
+## Boolean
+
+| Operator | Name | Return Type | 
+| --- | ----------- | --- | 
+| && | And | Boolean|
+| `||` | Or | Boolean|
+| ! | Not | Boolean|
+
+
+
+## More information
+
+* [Expressions repository](https://github.com/Kong/atc-router#table-of-contents)
+* [How to configure routes using Expressions](gateway/latest/understanding-kong/how-to/router-atc/)

src/gateway/understanding-kong/how-to/router-atc.md

@@ -0,0 +1,93 @@
+---
+title: How to Configure Routes using Expressions
+content-type: how-to
+---
+
+
+Expressions can describe routes or paths as patterns using regular expressions. This how-to guide will walk through switching to the new router, and configuring routes with the new expressive domain specific language, expressions. For a list of all available operators and configurable fields please review the [reference documentation](/gateway/latest/reference/router-operators).
+
+## Prerequisite
+
+Edit [kong.conf](/gateway/latest/kong-production/kong-conf) to contain the line `router_flavor = expressions` and restart {{site.base_gateway}}.
+
+## Create routes with Expressions
+
+To create a new router object using expressions, send a `POST` request to the [services endpoint](/gateway/latest/admin-api/#update-route) like this: 
+```sh
+curl --request POST \
+  --url http://localhost:8001/services/example-service/routes \
+  --form  atc='http.path == "/mock"
+```
+
+In this example, you associated a new route object with the path `/mock` to the existing service `example-service`. The Expressions DSL also allows you to create complex router objects using operators.  
+
+```sh
+curl --request POST \
+  --url http://localhost:8001/services/example-service/routes \
+  --header 'Content-Type: multipart/form-data' \
+  --form 'atc=(http.path == "/mock" || net.protocol == "https")'
+```
+In this example the || operator created an expression that set variables for the following fields: 
+
+```
+"protocols": ["http", "https"]
+AND
+"paths": ["/mock"]
+```
+
+You can use attributes that are unrelated to expressions within the same `POST` request:
+
+```sh
+curl --request POST \
+  --url http://localhost:8001/services/example-service/routes \
+  --header 'Content-Type: multipart/form-data' \
+  --form 'atc=(http.path == "/mock" || net.protocol == "https") \
+  --form name=mocking
+```
+
+This would define a router object with the following attributes:
+
+
+```
+"atc": "(http.path == \"\/mock\" || net.protocol == \"https\"),
+"name": "mocking",
+
+```
+You can view the list of available attributes in the [reference documentation](/gateway/latest/admin-api/#request-body). 
+
+
+
+### Create complex routes with Expressions
+
+You can describe complex route objects using operators within a `POST` request. 
+
+```sh
+
+curl --request POST \
+  --url http://localhost:8001/services/example-service/routes \
+  --header 'Content-Type: multipart/form-data' \
+  --form name=complex_object \
+  --form 'atc=(net.protocol == "http" || net.protocol == "https") &&
+         (http.method == "GET" || http.method == "POST") &&
+         (http.host == "example.com" || http.host == "example.test") &&
+         (http.path ^= "/mock" || http.path ^= "/mocking") &&
+         http.headers.x_another_header == "example_header" && (http.headers.x_my_header == "example" || http.headers.x_my_header == "example2")'
+```
+
+This request returns a `200` status code with the following values: 
+
+```sh
+"protocols": ["http", "https"],
+"methods": ["GET", "POST"],
+"hosts": ["example.com", "example.test"],
+"paths": ["/mock", "/mocking"],
+"headers": {"x-another-header":["example_header"], "x-my-header":["example", "example2"]},
+```
+
+For a list of all available operators, see the [reference documentation](/gateway/latest/reference/router-operators/).
+
+
+## More information
+
+* [Expressions repository](https://github.com/Kong/atc-router#table-of-contents)
+* [Expressions Reference](/gateway/latest/reference/router-operators)