Complete route, validator, directives docs

Author: Folyd

docs/guide/web/route.md

@@ -1,14 +1,22 @@
-# Route
+# Route and Endpoint
 
-**Route** is the main entrypoint that handles an HTTP request. All routes are defined in the `routes` directory.
+**Route** is the main entry point that handles an HTTP request in AIScript.
 
-## Define a route
+## Define An Endpoint
 
-Define a route is simple and straightforward. The syntax is:
+Defining an endpoint is simple and straightforward. The syntax is:
 
 ```
-verb path [(arg1: type1, arg2: type2, ...)] {
+verb path [, verb path...] {
+    // query parameters
+    query {
+        // parameter definitions
+    }
 
+    // request body
+    body {
+        // body field definitions
+    }
 }
 ```
 
@@ -30,12 +38,14 @@ get /hello {
 }
 ```
 
-```
+```bash
 $ curl http://localhost:8080/hello
 Hello World
 ```
 
-## Parse query string
+## Parse Query String
+
+Use the `query` block to declare fields in the query string. You can set a default value to make a parameter optional. To access query parameters, use the `query.name` or `query["name"]` syntax.
 
 ```py
 get /hello {
@@ -44,7 +54,7 @@ get /hello {
         name: str = "Alice"
     }
 
-    return "Hello, {name}!";
+    return "Hello, " + query.name + "!";
 }
 ```
 
@@ -53,43 +63,47 @@ $ curl http://localhost:8080/hello?name=AIScript
 Hello, AIScript!
 ```
 
-Each field declared in the `query` block is a query parameter, the `str` is the type of the query parameter. You can also specify a default value for the query parameter.
+Each field declared in the `query` block is a query parameter, with `str` indicating the parameter type.
 
 ```bash
 $ curl http://localhost:8080/hello
 Hello, Alice!
 ```
 
-The `@string` is a validator. AIScript will validate the query parameter and return an error if the validation fails.
+The [@string](/reference/directives#string) is a validator. AIScript will validate the query parameter and return an error if validation fails.
 
 ```bash
-$ curl http://localhost:8080/hello?name=WS
+$ curl http://localhost:8080/hello?name=Le
 {
     "error": "Invalid query parameter: name, must be between 3 and 10 characters"
 }
 ```
 
-## Parse request body
+:::tip
+For more information about validators, see [Validator](./validator.md).
+:::
+
+## Parse Request Body
 
-```js
+```py
 post /hello {
     @json
     body {
         @string(min_len=3, max_len=10)
         name: str
     }
 
-    return "Hello, {name}!";
+    return "Hello, " + body.name + "!";
 }
 ```
 
-```
+```bash
 $ curl -X POST -H "Content-Type: application/json" \
     -d '{"name": "AIScript"}' http://localhost:8080/hello
 Hello, AIScript!
 ```
 
-Each field declared in the `body` block is a request body parameter, the `str` is the type of the request body parameter. The `@json` directive tells AIScript to parse the request body as JSON. Another directive is `@form`, it tells AIScript to parse the request body as form data.
+Each field declared in the `body` block is a request body parameter, with `str` indicating the parameter type. The [@json](/reference/directives#json) directive tells AIScript to parse the request body as JSON. Alternatively, the [@form](/reference/directives#form) directive instructs AIScript to parse the request body as form data. Access body parameters using `body.name` or `body["name"]` syntax.
 
 ```py
 post /hello {
@@ -99,48 +113,48 @@ post /hello {
         name: str
     }
 
-    return "Hello, {name}!";
+    return "Hello, " + body.name + "!";
 }
 ```
 
-```
+```bash
 $ curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d 'name=AIScript' http://localhost:8080/hello
 Hello, AIScript!
 ```
 
-## Header and cookie
+## Headers and Cookies
 
-Access and set header and cookie is easy.
+Accessing and setting headers and cookies is straightforward using the `header` and `cookie` variables, which are request-scoped.
 
 ```py
 get /hello {
     let abc = header.abc;
     let xyz = cookie.xyz;
 
-    # set new header
+    // Set new header
     header.test = "Test Header";
-    # modify cookie
-    cookie.xyz = "{xyz} v2";
+    // Modify cookie
+    cookie.xyz = "changed";
     return "header: abc={abc}, cookie: xyz={xyz}";
 }
 ```
 
-## Request object
+## Request Object
 
 ```py
 get /hello {
     let method = request.method;
-    let url = request.url
-    let path = request.path
-    let scheme = request.scheme
-    let host = request.host
-    let port = request.port
-    return "method: {method}, url: {url}, path: {path}, scheme: {scheme}, host: {host}, port: {port}"
+    let url = request.url;
+    let path = request.path;
+    let scheme = request.scheme;
+    let host = request.host;
+    let port = request.port;
+    return "method: {method}, url: {url}, path: {path}, scheme: {scheme}, host: {host}, port: {port}";
 }
 ```
 
-```
+```bash
 $ curl http://localhost:8080/hello
 method: GET, url: http://localhost:8080/hello, path: /hello, scheme: http, host: localhost, port: 8000
 ```
@@ -149,22 +163,26 @@ method: GET, url: http://localhost:8080/hello, path: /hello, scheme: http, host:
 
 ```py
 get /hello {
-    return temporaly_redirect("/hello2")
+    return temporary_redirect("/hello2");
+}
+
+get /hello2 {
+    return "Hello, World!";
 }
 ```
 
-## Path parameter
+## Path Parameters
 
 ```py
 get /hello/<name:str> {
     return "Hello, {name}!";
 }
 ```
 
-## Multiple routes
+## Multiple Routes
 
-```rust
-get /hello {
+```py
+get /hello, get /world {
     return "Hello, World!";
 }
 
@@ -173,30 +191,30 @@ post /hello2 {
 }
 ```
 
-## Route programming
+## Route Programming
 
-API routes normally never a simple text response, it often need programming logic to handle the request. In AIScript route, you can write any programming logic in the route just like other web frameworks in ohter languages.
+API routes typically require more than simple text responses; they often need programming logic to handle requests. In AIScript routes, you can write any programming logic just as you would in other web frameworks.
 
-```rust
+```py
 get /hello {
     query {
         value: int
     }
 
-    if value > 10 {
+    if query.value > 10 {
         return "Value is greater than 10";
-    else {
+    } else {
         return "Value is less than or equal to 10";
     }
 }
 ```
 
-```
+```bash
 $ curl http://localhost:8080/hello?value=11
 Value is greater than 10
 ```
 
-## Query database with SQL
+## Query Database with SQL
 
 ```py
 get /tweet/<id: int> {
@@ -205,4 +223,3 @@ get /tweet/<id: int> {
     return pg.query("SELECT * FROM tweet WHERE id = $1", id);
 }
 ```
-