You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/03/02 22:20:43 UTC
[apisix] branch master updated: docs: restructure the "Architecture Design" Section (#6464)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new fdad0ae docs: restructure the "Architecture Design" Section (#6464)
fdad0ae is described below
commit fdad0aea0b1fbcba050bf5ed00b8801c40a6da16
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Thu Mar 3 03:49:09 2022 +0530
docs: restructure the "Architecture Design" Section (#6464)
Signed-off-by: Navendu Pottekkat <na...@gmail.com>
---
docs/en/latest/architecture-design/apisix.md | 20 +++++++----
docs/en/latest/architecture-design/consumer.md | 30 +++++++++--------
docs/en/latest/architecture-design/debug-mode.md | 33 +++++++++---------
docs/en/latest/architecture-design/global-rule.md | 13 ++++----
.../en/latest/architecture-design/plugin-config.md | 16 ++++-----
docs/en/latest/architecture-design/plugin.md | 39 +++++++++++++---------
docs/en/latest/architecture-design/route.md | 24 ++++++++-----
docs/en/latest/architecture-design/router.md | 22 +++++++-----
docs/en/latest/architecture-design/script.md | 10 +++---
docs/en/latest/architecture-design/service.md | 12 ++++---
docs/en/latest/architecture-design/upstream.md | 36 ++++++++++----------
11 files changed, 144 insertions(+), 111 deletions(-)
diff --git a/docs/en/latest/architecture-design/apisix.md b/docs/en/latest/architecture-design/apisix.md
index f5d262e..8bef622 100644
--- a/docs/en/latest/architecture-design/apisix.md
+++ b/docs/en/latest/architecture-design/apisix.md
@@ -33,19 +33,23 @@ title: APISIX

-## Configure APISIX
+## Configuring APISIX
-There are two methods to configure APISIX: directly change `conf/config.yaml`, or add file path argument using `-c` or `--config` flag when start APISIX like `apisix start -c <path string>`
+Apache APISIX can be configured in two ways:
-For example, set the default listening port of APISIX to 8000, and keep other configurations as default. The configuration in `config.yaml` should be like this:
+1. By directly changing `conf/config.yaml`.
+2. Using the `--config` or the `-c` flag to pass in the file path of your config file while starting APISIX (`apisix start -c <path to config file>`).
+
+Configurations can be added to this YAML file and Apache APISIX will fall back to the default configurations for anything that is not configured in this file.
+
+For example, to set the default listening port to 8000 while keeping other configurations as default, your configuration file (`config.yaml`) would look like:
```yaml
apisix:
node_listen: 8000 # APISIX listening port
```
-Set the default listening port of APISIX to 8000, set the `etcd` address to `http://foo:2379`,
-and keep other configurations as default. The configuration in `config.yaml` should be like this:
+Similarly, to set the listening port to 8000 and set the etcd address to `http://foo:2379` while keeping other configurations as default, your configuration file would look like:
```yaml
apisix:
@@ -55,6 +59,8 @@ etcd:
host: "http://foo:2379" # etcd address
```
-Other default configurations can be found in the `conf/config-default.yaml` file, which is bound to the APISIX source code. **Never** manually modify the `conf/config-default.yaml` file. If you need to customize any configuration, you should update the `config.yaml` file.
+Default configurations of APISIX can be found in the `conf/config-default.yaml` file.
+
+**Note**: This file is bound to the APISIX source code and should **NOT** be modified. The configuration should only be changed by the methods mentioned above.
-**Note** `APISIX` will generate `conf/nginx.conf` file automatically, so please _DO NOT EDIT_ `conf/nginx.conf` file too.
+**Note**: The `conf/nginx.conf` file is automatically generated by APISIX and should **NOT** be edited.
diff --git a/docs/en/latest/architecture-design/consumer.md b/docs/en/latest/architecture-design/consumer.md
index 3710338..e41eb65 100644
--- a/docs/en/latest/architecture-design/consumer.md
+++ b/docs/en/latest/architecture-design/consumer.md
@@ -21,32 +21,34 @@ title: Consumer
#
-->
-For the API gateway, it is usually possible to identify a certain type of requester by using a domain name such as a request domain name, a client IP address, etc., and then perform plugin filtering and forward the request to the specified upstream, but sometimes the depth is insufficient.
+For an API gateway, it is usually possible to identify the type of the requester by using things like their request domain name and client IP address. A gateway like APISIX can then filter these requests using [Plugins](./plugin.md) and forward it to the specified [Upstream](./upstream.md).
+
+But this level of depth can be insufficient in some occasions.

-As shown in the image above, as an API gateway, you should know who the API Consumer is, so you can configure different rules for different API Consumers.
+An API gateway should know who the consumer of the API is to configure different rules for different consumers.
+
+This is where the Consumer construct comes in APISIX. The fields are defined below.
| Field | Required | Description |
| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| username | Yes | Consumer Name. |
-| plugins | No | The corresponding plugin configuration of the Consumer, which has the highest priority: Consumer > Route > Service. For specific plugin configurations, refer to the [Plugins](plugin.md) section. |
+| username | Yes | Name of the consumer. |
+| plugins | No | Plugin configuration of the Consumer. It has the highest priority: Consumer > Route > Service. For specific Plugin configurations, refer the [Plugins](./plugin.md) section. |
-In APISIX, the process of identifying a Consumer is as follows:
+The process of identifying a Consumer in APISIX is described below:

-1. Authorization certification: e.g [key-auth](../plugins/key-auth.md), [JWT](../plugins/jwt-auth.md), etc.
-2. Get consumer_name: By authorization, you can naturally get the corresponding Consumer `id`, which is the unique identifier of the Consumer object.
-3. Get the Plugin or Upstream information bound to the Consumer: Complete the different configurations for different Consumers.
-
-To sum up, Consumer is a consumer of certain types of services and needs to be used in conjunction with the user authentication system.
+1. The first step is Authentication. This is achieved by Authentication Plugins like [key-auth](../plugins/key-auth.md) and [JWT](../plugins/jwt-auth.md).
+2. After authenticating, you can obtain the `id` of the Consumer. This `id` will be the unique identifier of a Consumer.
+3. The configurations like Plugins and Upstream bound to the Consumer are then executed.
-For example, different consumers request the same API, and the gateway service corresponds to different Plugin or Upstream configurations according to the current request user information.
+Consumers are useful when you have different consumers requesting the same API and you need to execute different Plugin and Upstream configurations based on the consumer. These need to be used in conjunction with the user authentication system.
-In addition, you can refer to the [key-auth](../plugins/key-auth.md) authentication authorization plugin call logic to help you further understand the Consumer concept and usage.
+Refer the documentation for the [key-auth](../plugins/key-auth.md) authentication Plugin to further understand the concept of a Consumer.
-How to enable a specific plugin for a Consumer, you can see the following example:
+The example below shows how you can enable a Plugin for a specific Consumer.
```shell
# Create a Consumer, specify the authentication plugin key-auth, and enable the specific plugin limit-count
@@ -95,7 +97,7 @@ HTTP/1.1 503 Service Temporarily Unavailable
```
-Use the [consumer-restriction](../plugins/consumer-restriction.md) plug-in to restrict the access of Jack to this API.
+We can use the [consumer-restriction](../plugins/consumer-restriction.md) Plugin to restrict our user "Jack" from accessing the API.
```shell
# Add Jack to the blacklist
diff --git a/docs/en/latest/architecture-design/debug-mode.md b/docs/en/latest/architecture-design/debug-mode.md
index 5c66343..792c2bb 100644
--- a/docs/en/latest/architecture-design/debug-mode.md
+++ b/docs/en/latest/architecture-design/debug-mode.md
@@ -23,16 +23,16 @@ title: Debug Mode
### Basic Debug Mode
-Enable basic debug mode via `conf/debug.yaml` file:
+You can enable the basic debug mode by adding this line to your `conf/debug.yaml` file.
```
basic:
enable: true
```
-Note: before APISIX 2.10, we enabled basic debug mode by setting `apisix.enable_debug = true` in `conf/config.yaml` file.
+**Note**: Before Apache APISIX 2.10, basic debug mode was enabled by setting `apisix.enable_debug = true` in the `conf/config.yaml` file.
-e.g Using both `limit-conn` and `limit-count` plugins for a `/hello` request, there will have a response header called `Apisix-Plugins: limit-conn, limit-count`.
+For example, if we are using two plugins `limit-conn` and `limit-count` for a Route `/hello`, we will receive a response with the header `Apisix-Plugins: limit-conn, limit-count` when we enable the basic debug mode.
```shell
$ curl http://127.0.0.1:1984/hello -i
@@ -48,22 +48,25 @@ Server: openresty
hello world
```
-If the information can not be delivered via HTTP response header, for example, the plugin is in stream
-subsystem, the information will be logged in the error log with `warn` level.
+If the debug information cannot be included in a response header (say when the plugin is in a stream subsystem), the information will be logged in the error log at a `warn` level.
### Advanced Debug Mode
-Enable advanced debug mode by modifying the configuration in `conf/debug.yaml` file. Because there will be a check every second, only the checker reads the `#END` flag, and the file would be considered as closed.
+Advanced debug mode can also be enabled by modifying the configuration in the `conf/debug.yaml` file.
-The checker would judge whether the file data changed according to the last modification time of the file. If there has any change, reload it. If there was no change, skip this check. So it's hot reload for enabling or disabling advanced debug mode.
+Enable advanced debug mode by modifying the configuration in `conf/debug.yaml` file.
+
+The checker checks every second for changes to the configuration files. An `#END` flag is added to let the checker know that it should only look for changes till that point.
+
+The checker would only check this if the file was updated by checking its last modification time.
| Key | Optional | Description | Default |
| ------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| hook_conf.enable | required | Enable/Disable hook debug trace. Target module function's input arguments or returned value would be printed once this option is enabled. | false |
-| hook_conf.name | required | The module list name of hook which has enabled debug trace. | |
-| hook_conf.log_level | required | Logging levels for input arguments & returned value. | warn |
-| hook_conf.is_print_input_args | required | Enable/Disable input arguments print. | true |
-| hook_conf.is_print_return_value | required | Enable/Disable returned value print. | true |
+| hook_conf.name | required | The module list name of the hook which has enabled debug trace. | |
+| hook_conf.log_level | required | Logging levels for input arguments & returned values. | warn |
+| hook_conf.is_print_input_args | required | Enable/Disable printing input arguments. | true |
+| hook_conf.is_print_return_value | required | Enable/Disable printing returned values. | true |
Example:
@@ -86,9 +89,9 @@ hook_phase: # Module Function List, Name: hook_phase
### Enable Advanced Debug Mode Dynamically
-The advanced debug mode can take effect in particular requests by dynamic rule.
+You can also enable the advanced debug mode to take effect on particular requests.
-Example:
+For example, to dynamically enable advanced debugging mode on requests with a particular header name `X-APISIX-Dynamic-Debug` you can configure:
```yaml
http_filter:
@@ -98,10 +101,10 @@ http_filter:
#END
```
-Dynamically enable advanced debugging mode in a particular request like this:
+This will enable the advanced debug mode for requests like:
```shell
curl 127.0.0.1:9090/hello --header 'X-APISIX-Dynamic-Debug: foo'
```
-Notice: We can not hook the `apisix.http_access_phase` module for particular requests, since whether the advanced debug mode is enabled is determined after these requests enter such phase.
+**Note**: The `apisix.http_access_phase` module cannot be hooked for dynamic rules as the advanced debug mode is enabled based on the request.
diff --git a/docs/en/latest/architecture-design/global-rule.md b/docs/en/latest/architecture-design/global-rule.md
index cb9615e..a38084c 100644
--- a/docs/en/latest/architecture-design/global-rule.md
+++ b/docs/en/latest/architecture-design/global-rule.md
@@ -1,5 +1,5 @@
---
-title: Global rule
+title: Global Rule
---
<!--
@@ -21,8 +21,11 @@ title: Global rule
#
-->
-The [Plugin](plugin.md) configuration can be bound directly to a [Route](route.md), or to a [Service](service.md) or [Consumer](consumer.md). What if we want a [Plugin](plugin.md) to work on all requests, how to do it?
-We can register a global [Plugin](plugin.md) with `GlobalRule`:
+A [Plugin](./plugin.md) configuration can be bound directly to a [Route](./route.md), a [Service](./service.md) or a [Consumer](./consumer.md). But what if we want a Plugin to work on all requests?
+
+This is where we register a global Plugin with Global Rule.
+
+The example below shows how you can use the `limit-count` Plugin on all requests:
```shell
curl -X PUT \
@@ -42,9 +45,7 @@ curl -X PUT \
}'
```
-Now, the `limit-count` plugin will work on all requests
-
-we can list all `GlobalRule` via admin api as below:
+You can also list all the Global rules by making this request with the Admin API:
```shell
curl https://{apisix_listen_address}/apisix/admin/global_rules
diff --git a/docs/en/latest/architecture-design/plugin-config.md b/docs/en/latest/architecture-design/plugin-config.md
index 84de448..075562f 100644
--- a/docs/en/latest/architecture-design/plugin-config.md
+++ b/docs/en/latest/architecture-design/plugin-config.md
@@ -21,10 +21,9 @@ title: Plugin Config
#
-->
-To reuse common plugin configurations, you can extract them into a plugin config and
-bind it with a route directly.
+Plugin Configs are used to extract commonly used [Plugin](./plugin.md) configurations and can be bound directly to a [Route](./route.md).
-For instance, you can do something like:
+The example below illustrates how this can be used:
```shell
# create a plugin config
@@ -54,12 +53,11 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
}'
```
-When we can't find the corresponding plugin config with the id, the requests hit the route will be terminated with HTTP status code 503.
+When APISIX can't find the Plugin Config with the `id`, the requests reaching this Route are terminated with a status code of 503.
-When a route already have `plugins` field configured, the `plugins` in the plugin config
-will be merged into it. The same plugin in the plugin config will override one in the `plugins`.
+If a Route already has the `plugins` field configured, the plugins in the Plugin Config will effectively be merged to it. The same plugin in the Plugin Config will override the ones configured directly in the Route.
-For example, when we configure a plugin config
+For example, if we configure a Plugin Config as shown below
```
{
@@ -80,7 +78,7 @@ For example, when we configure a plugin config
}
```
-to
+to a Route as shown below,
```
{
@@ -108,7 +106,7 @@ to
}
```
-is equal to
+the effective configuration will be as the one shown below:
```
{
diff --git a/docs/en/latest/architecture-design/plugin.md b/docs/en/latest/architecture-design/plugin.md
index cda1e8e..a325719 100644
--- a/docs/en/latest/architecture-design/plugin.md
+++ b/docs/en/latest/architecture-design/plugin.md
@@ -21,17 +21,21 @@ title: Plugin
#
-->
-`Plugin` represents the plugin configuration that will be executed during the `HTTP` request/response lifecycle.
+This represents the configuration of the plugins that are executed during the HTTP request/response lifecycle.
-The `Plugin` configuration can be bound directly to `Route` or it can be bound to `Service` or `Consumer`. For the configuration of the same plugin, only one copy is valid, and the configuration selection priority is always `Consumer` > `Route` > `Service`.
+A `Plugin` configuration can be bound directly to a [`Route`](./route.md), a [`Service`](./service.md) or a [`Consumer`](./consumer.md).
-In `conf/config.yaml`, you can declare which plugins are supported by the local APISIX node. This is a whitelisting mechanism. Plugins that are not in this whitelist will be automatically ignored. This feature can be used to temporarily turn off or turn on specific plugins, which is very effective in dealing with unexpected situations. If you want to add new plugins based on existing plugins, you need to copy the data of `plugins` node which in `conf/config-default.yaml` to the `plugins` [...]
+**Note**: While configuring the same plugin, only one copy of the configuration is valid. The order of precedence is always `Consumer` > `Route` > `Service`.
-The configuration of the plugin can be directly bound to the specified Route, or it can be bound to the Service, but the plugin configuration in Route has a higher priority.
+While [configuring APISIX](./apisix.md#configuring-apisix), you can declare the Plugins that are supported by the local APISIX node.
-A plugin will only be executed once in a single request, even if it is bound to multiple different objects (such as Route or Service).
+This acts as a whitelisting mechanism as Plugins that are not in this whitelist will be automatically ignored. So, this feature can be used to temporarily turn off/turn on specific plugins.
-The order in which plugins are run is determined by the priority of the plugin itself, for example:
+For adding new plugins based on existing plugins, copy the data in the the `plugins` node from the default configuration file `conf/config-default.yaml` to your configuration file (`conf/config.yaml`).
+
+In a request, a Plugin is only executed once. This is true even if it is bound to multiple different objects like Routes and Services.
+
+The order in which Plugins are run is determined by its configured priorities:
```lua
local _M = {
@@ -43,7 +47,7 @@ local _M = {
}
```
-The plugin configuration is submitted as part of Route or Service and placed under `plugins`. It internally uses the plugin name as the hash's key to hold configuration items for different plugins.
+A Plugin configuration is submitted as part of the Route or Service and is placed under `plugins`. It internally uses the Plugin name as the hash key to hold the configuration items for the different Plugins.
```json
{
@@ -60,23 +64,28 @@ The plugin configuration is submitted as part of Route or Service and placed und
}
```
-Not all plugins have specific configuration items. For example, there is no specific configuration item under `prometheus`. In this case, an empty object identifier can be used.
+Not all Plugins have specific configuration items (for example, [prometheus](/docs/apisix/plugins/prometheus/)). In such cases, an empty object identifier can be used.
+
+A warn level log as shown below indicates that the request was rejected by the Plugin.
+
+```shell
+ip-restriction exits with http status code 403
+```
-If a request is rejected by a plugin, there will be warn level log like `ip-restriction exits with http status code 403`.
+## Hot Reload
-## Hot reload
+APISIX Plugins are hot-loaded.
-APISIX plugins are hot-loaded. No matter you add, delete or modify plugins, and **update codes of plugins in disk**, you don't need to restart the service.
+This means that there is no need to restart the service if you add, delete, modify plugins or even if you update the plugin code.
-If your APISIX node has the Admin API turned on, just send an HTTP request through admin API:
+To hot-reload, you can send an HTTP request through the [Admin API](../admin-api.md):
```shell
curl http://127.0.0.1:9080/apisix/admin/plugins/reload -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT
```
-Note: if you disable a plugin that has been configured as part of your rule (in the `plugins` field of `route`, etc.),
-then its execution will be skipped.
+**Note**: If a configured Plugin is disabled, then its execution will be skipped.
### Hot reload in stand-alone mode
-For stand-alone mode, see plugin related section in [stand alone mode](../stand-alone.md).
+For hot-reloading in stand-alone mode, see the plugin related section in [stand alone mode](../stand-alone.md).
diff --git a/docs/en/latest/architecture-design/route.md b/docs/en/latest/architecture-design/route.md
index 57a2449..e287e99 100644
--- a/docs/en/latest/architecture-design/route.md
+++ b/docs/en/latest/architecture-design/route.md
@@ -21,19 +21,25 @@ title: Route
#
-->
-The route matches the client's request by defining rules, then loads and executes the corresponding plugin based on the matching result, and forwards the request to the specified Upstream.
+Routes match the client's request based on defined rules, loads and executes the corresponding [plugins](./plugin.md), and forwards the request to the specified [Upstream](./upstream.md).
-The route mainly consists of three parts: matching rules (e.g uri, host, remote_addr, etc.), plugin configuration (current-limit & rate-limit, etc.) and upstream information.
+A Route mainly consists of three parts:
-The following image shows an example of some Route rules. When some attribute values are the same, the figure is identified by the same color.
+1. Matching rules (uri, host, remote address)
+2. Plugin configuration (current-limit, rate-limit)
+3. Upstream information
+
+The image below shows some example Route rules. Note that the values are of the same color if they are identical.

-We configure all the parameters directly in the Route, it's easy to set up, and each Route has a relatively high degree of freedom. But when our Route has more repetitive configurations (such as enabling the same plugin configuration or upstream information), once we need update these same properties, we have to traverse all the Routes and modify them, so it's adding a lot of complexity of management and maintenance.
+All the parameters are configured directly in the Route. It is easy to set up, and each Route has a high degree of freedom.
+
+When Routes have repetitive configurations (say, enabling the same plugin configuration or Upstream information), to update it, we need to traverse all the Routes and modify them. This adds a lot of complexity, making it difficult to maintain.
-The shortcomings mentioned above are independently abstracted in APISIX by the two concepts [Service](service.md) and [Upstream](upstream.md).
+These shortcomings are independently abstracted in APISIX by two concepts: [Service](service.md) and [Upstream](upstream.md).
-The route example created below is to proxy the request with URL `/index.html` to the Upstream service with the address `127.0.0.1:1980`:
+The Route example shown below proxies the request with the URL `/index.html` to the Upstream service with the address `127.0.0.1:1980`.
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
@@ -46,7 +52,9 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
}
}
}'
+```
+```shell
HTTP/1.1 201 Created
Date: Sat, 31 Aug 2019 01:17:15 GMT
Content-Type: text/plain
@@ -57,6 +65,6 @@ Server: APISIX web server
{"node":{"value":{"uri":"\/index.html","upstream":{"nodes":{"127.0.0.1:1980":1},"type":"roundrobin"}},"createdIndex":61925,"key":"\/apisix\/routes\/1","modifiedIndex":61925},"action":"create"}
```
-When we receive a successful response, it indicates that the route was successfully created.
+A successful response indicates that the route was created.
-For specific options of Route, please refer to [Admin API](../admin-api.md#route).
+For specific options of Route, please refer to the [Admin API](../admin-api.md#route).
diff --git a/docs/en/latest/architecture-design/router.md b/docs/en/latest/architecture-design/router.md
index 4dbd970..58db1a6 100644
--- a/docs/en/latest/architecture-design/router.md
+++ b/docs/en/latest/architecture-design/router.md
@@ -21,19 +21,23 @@ title: Router
#
-->
-A distinguishing feature of APISIX from other API gateways is that it allows users to choose different routers to better match free services, making the best choice between performance and freedom.
+A distinguishing feature of Apache APISIX from other API gateways is that it allows you to choose different Routers to better match free services, giving you the best choices for performance and freedom.
+
+You can set the Router that best suits your needs in your configuration file (conf/config.yaml).
Set the route that best suits your business needs in the local configuration `conf/config.yaml`.
-- `apisix.router.http`: HTTP Request Route。
+It can have the following configurations:
+
+- `apisix.router.http`: The HTTP request route. It can take the following values:
- - `radixtree_uri`: (Default) only use `uri` as the primary index. Support for full and deep prefix matching based on the `radixtree` engine, see [How to use router-radixtree](../router-radixtree.md).
- - `Absolute match`: Complete match for the given `uri`, such as `/foo/bar`,`/foo/glo`.
- - `Prefix match`: Use `*` at the end to represent the given `uri` as a prefix match. For example, `/foo*` allows matching `/foo/`, `/foo/a` and `/foo/b`.
- - `match priority`: first try absolute match, if you can't hit absolute match, try prefix match.
- - `Any filter attribute`: Allows you to specify any Nginx built-in variable as a filter, such as URL request parameters, request headers, cookies, and so on.
- - `radixtree_uri_with_parameter`: Like `radixtree_uri` but also support parameter match.
- - `radixtree_host_uri`: Use `host + uri` as the primary index (based on the `radixtree` engine), matching both host and URL for the current request.
+ - `radixtree_uri`: (Default) Only use the `uri` as the primary index. To learn more about the support for full and deep prefix matching, check [How to use router-radixtree](../router-radixtree.md).
+ - `Absolute match`: Match completely with the given `uri` (`/foo/bar`, `/foo/glo`).
+ - `Prefix match`: Match with the given prefix. Use `*` to represent the given `uri` for prefix matching. For example, `/foo*` can match with `/foo/`, `/foo/a` and `/foo/b`.
+ - `match priority`: First try an absolute match, if it didn't match, try prefix matching.
+ - `Any filter attribute`: Allows you to specify any Nginx built-in variable as a filter, such as URL request parameters, request headers, and cookies.
+ - `radixtree_uri_with_parameter`: Like `radixtree_uri` but also supports parameter match.
+ - `radixtree_host_uri`: Matches both host and URI of the request. Use `host + uri` as the primary index (based on the `radixtree` engine).
- `apisix.router.ssl`: SSL loads the matching route.
- `radixtree_sni`: (Default) Use `SNI` (Server Name Indication) as the primary index (based on the radixtree engine).
diff --git a/docs/en/latest/architecture-design/script.md b/docs/en/latest/architecture-design/script.md
index 0987d49..3e77b28 100644
--- a/docs/en/latest/architecture-design/script.md
+++ b/docs/en/latest/architecture-design/script.md
@@ -21,15 +21,13 @@ title: Script
#
-->
-`Script` represents a script that will be executed during the `HTTP` request/response life cycle.
+Scripts lets you write arbitrary Lua code or directly call existing plugins and execute them during the HTTP request/response lifecycle.
-The `Script` configuration can be directly bound to the `Route`.
+A Script configuration can be directly bound to a [Route](./route.md).
-`Script` and `Plugin` are mutually exclusive, and `Script` is executed first. This means that after configuring `Script`, the `Plugin` configured on `Route` will not be executed.
+Scripts and [Plugins](./plugin.md) are mutually exclusive, and a Script is executed before a Plugin. This means that after configuring a Script, the Plugin configured on the Route will **not** be executed.
-In theory, you can write arbitrary Lua code in `Script`, or you can directly call existing plugins to reuse existing code.
-
-`Script` also has the concept of execution phase, supporting `access`, `header_filter`, `body_filter` and `log` phase. The system will automatically execute the code of the corresponding phase in the `Script` script in the corresponding phase.
+Scripts also have a concept of execution phase which supports the `access`, `header_filter`, `body_filter` and the `log` phase. The corresponding phase will be executed automatically by the system in the Script.
```json
{
diff --git a/docs/en/latest/architecture-design/service.md b/docs/en/latest/architecture-design/service.md
index f2238c9..019bcd5 100644
--- a/docs/en/latest/architecture-design/service.md
+++ b/docs/en/latest/architecture-design/service.md
@@ -21,13 +21,15 @@ title: Service
#
-->
-A `Service` is an abstraction of an API (which can also be understood as a set of Route abstractions). It usually corresponds to the upstream service abstraction. Between `Route` and `Service`, usually the relationship of N:1, please see the following image.
+A Service is an abstraction of an API (which can also be understood as a set of [Route](./route.md) abstractions). It usually corresponds to an upstream service abstraction.
+
+The relationship between Routes and a Service is usually N:1 as shown in the image below.

-Different Route rules are bound to a Service at the same time. These Routes will have the same upstream and plugin configuration, reducing redundant configuration.
+As shown, different Routes could be bound to the same Service. This reduces redundancy as these bounded Routes will have the same [Upstream](./upstream.md) and [Plugin](./plugin.md) configurations.
-The following example creates a Service that enables the current-limit plugin, and then binds the Route with the id of `100` and `101` to the Service.
+The following example creates a Service that enables the current-limit Plugin, and then binds it to the Routes with the ids `100` and `101`.
```shell
# create new Service
@@ -65,7 +67,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/101 -H 'X-API-KEY: edd1c9f034335f
}'
```
-Of course, we can also specify different plugin parameters or upstream for Route. Some of the following Routes have different current-limit parameters. Other parts (such as upstream) continue to use the configuration parameters in Service.
+We can also specify different Plugins or Upstream for the Routes than the ones defined in the Service. The example below creates a Route with a limit-count Plugin. This Route will continue to use the other configurations defined in the Service (here, the Upstream configuration).
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/102 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -84,4 +86,4 @@ curl http://127.0.0.1:9080/apisix/admin/routes/102 -H 'X-API-KEY: edd1c9f034335f
}'
```
-Note: When both Route and Service enable the same plugin, the Route parameter has a higher priority than Service.
+**Note**: When a Route and a Service enable the same Plugin, the one defined in the Route is given the higher priority.
diff --git a/docs/en/latest/architecture-design/upstream.md b/docs/en/latest/architecture-design/upstream.md
index e8d8e11..e00bd88 100644
--- a/docs/en/latest/architecture-design/upstream.md
+++ b/docs/en/latest/architecture-design/upstream.md
@@ -21,19 +21,21 @@ title: Upstream
#
-->
-Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to configuration rules. Upstream address information can be directly configured to `Route` (or `Service`). When Upstream has duplicates, you need to use "reference" to avoid duplication.
+Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to the configured rules.
+
+Although Upstream can be directly configured to the [Route](./route.md) or [Service](./route.md), using an Upstream object is recommended when there is duplication as shown below.

-As shown in the image above, by creating an Upstream object and referencing it by ID in `Route`, you can ensure that only the value of an object is maintained.
+By creating an Upstream object and referencing it by `upstream_id` in the Route, you can ensure that there is only a single value of the object that needs to be maintained.
-Upstream configuration can be directly bound to the specified `Route` or it can be bound to `Service`, but the configuration in `Route` has a higher priority. The priority behavior here is very similar to `Plugin`.
+An Upstream configuration can be directly bound to a Route or a Service, but the configuration in Route has a higher priority. This behavior is consistent with priority followed by the [Plugin](./plugin.md) object.
### Configuration
-In addition to the basic complex equalization algorithm selection, APISIX's Upstream also supports logic for upstream passive health check and retry, see [this link](../admin-api.md#upstream).
+In addition to the equalization algorithm selections, Upstream also supports passive health check and retry for the upstream. You can learn more about this [here](../admin-api.md#upstream).
-Create an upstream object use case:
+To create an Upstream object, you can use the Admin API as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -47,7 +49,7 @@ curl http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335
}'
```
-After the upstream object is created, it can be referenced by specific `Route` or `Service`, for example:
+After creating an Upstream object, it can be referenced by a specific Route or Service as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -57,7 +59,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-For convenience, you can also directly bind the upstream address to a `Route` or `Service`, for example:
+For convenience, you can directly bind the upstream address to a Route or Service:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -80,7 +82,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Here's an example of configuring a health check:
+The example below shows how you can configure a health check:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -118,13 +120,13 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-More details can be found in [Health Checking Documents](../health-check.md).
+You can learn more about health checks [here](../health-check.md).
-Here are some examples of configurations using different `hash_on` types:
+The examples below shows configurations which uses different `hash_on` types.
#### Consumer
-Create a consumer object:
+Creating a Consumer object:
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -138,7 +140,7 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}'
```
-Create route object and enable `key-auth` plugin authentication:
+Creating a Route object and enabling the `key-auth` authentication Plugin:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -158,7 +160,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Test request, the `consumer_name` after authentication is passed will be used as the hash value of the load balancing hash algorithm:
+To test the request, the `consumer_name` passed for authentication will be used as the hash value of the load balancing hash algorithm.
```shell
curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"
@@ -166,7 +168,7 @@ curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"
#### Cookie
-Create route and upstream object, `hash_on` is `cookie`:
+Creating a Route and an upstream object:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -184,7 +186,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-The client requests with `Cookie`:
+The client can then send a request with a cookie:
```shell
curl http://127.0.0.1:9080/hash_on_cookie -H "Cookie: sid=3c183a30cffcda1408daf1c61d47b274"
@@ -192,7 +194,7 @@ The client requests with `Cookie`:
#### Header
-Create route and upstream object, `hash_on` is `header`, `key` is `Content-Type`:
+Creating a Route and an upstream object:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -210,7 +212,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-The client requests with header `Content-Type`:
+The client can now send requests with a header. The example below shows using the header `Content-Type`:
```shell
curl http://127.0.0.1:9080/hash_on_header -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -H "Content-Type: application/json"