Skip to main content
API7.ai Logo
Version: 3.19.0

Plugin Common Configurations

Plugin common configurations are a set of configuration options that can be applied universally to all APISIX plugins through the _meta attribute. They can be used to configure:

_meta.filter​

You can use _meta.filter to configure the conditional execution of plugins based on request parameters. Conditions are created with APISIX expressions and configured as an array. A plugin only executes when all conditions are met.

For example, the following configuration sets a condition on the request's URI query parameter. Only requests with the URI query parameter version being v2 will trigger the execution of the proxy-rewrite plugin, which rewrites the request's URI path to /api/v2 before forwarding it to the upstream:

{
  ...,
  "plugins": {
    "proxy-rewrite": {
      "uri": "/api/v2",
      "_meta": {
        "filter": [
          ["arg_version", "==", "v2"]
        ]
      }
    }
  }
}

Requests not meeting the condition will not have their URI paths rewritten and will be forwarded as-is.

_meta.priority​

You can use _meta.priority to adjust the execution order of plugins of the same type (i.e. global or non-global) within a given phase. Once defined, the value will take precedence over the default plugin priority defined in the configuration file.

Suppose two plugins that run in the same phase, limit-count and ip-restriction, are configured on the same route. limit-count has a default priority of 1002 and ip-restriction has a default priority of 3000. When a request is sent to the route, ip-restriction is executed first as it has a higher default priority value. However, you can run limit-count before ip-restriction by assigning _meta.priority of limit-count a priority value higher than 3000, such as:

{
  ...,
  "plugins": {
    "limit-count": {
      ...,
      "_meta": {
        "priority": 3010
      }
    }
  }
}

To learn more about the execution order when global and non-global plugins are used together, see plugin execution order.

_meta.disable​

You can use _meta.disable to disable a plugin without removing the plugin from the object it is bound to entirely.

For example, you can disable the proxy-rewrite plugin with the following:

{
  "plugins": {
    "proxy-rewrite": {
      "_meta": {
        "disable": true
      }
    }
  }
}

_meta.error_response​

You can use _meta.error_response to replace the error response returned by a plugin with a fixed value. This can simplify client handling when the default response is unsuitable.

For example, you can customize the error response of the limit-count plugin:

{
  "plugins": {
    "limit-count": {
      "count": 1,
      "time_window": 60,
      "_meta": {
        "error_response": {
          "message": "You have exceeded the rate limiting threshold."
        }
      }
    }
  }
}

If more than one request is sent within the 60-second window to the route that the plugin binds to, you should see the following response:

{"message":"You have exceeded the rate limiting threshold."}

_meta.pre_function​

You can use _meta.pre_function to run custom code before a plugin executes in each phase.

The following example demonstrates how to configure _meta.pre_function in proxy-rewrite, register the request path's user_id parameter as a variable, and use the variable in the rewritten path.

To use route URI parameters, set the router to radixtree_uri_with_parameter in the configuration file:

config.yaml
apisix:
  router:
    http: radixtree_uri_with_parameter

Then reload APISIX for the changes to take effect.

Create a route to the httpbin service to examine the rewritten path:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
  "id": "pre-func-route",
  "uri": "/anything/:user_id/hello",
  "plugins": {
    "proxy-rewrite": {
      "_meta": {
        "pre_function": "return function(conf, ctx) local core = require \"apisix.core\" core.ctx.register_var(\"user_id\", function(ctx) return ctx.curr_req_matched.user_id end) end"
      },
      "uri": "/anything/$user_id/world"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

❶ Match requests to /anything/:user_id/hello where user_id is a parameter.

❷ Customize the _meta.pre_function to extract the user_id value from the requested path and save it to a variable of the same name.

❸ Rewrite the request path to /anything/$user_id/world, where $user_id will be replaced by the variable value.

Send a request to the route:

curl -i "http://127.0.0.1:9080/anything/johndoe/hello"

The response should contain the rewritten URL with the value of user_id:

{
  "url": "http://127.0.0.1/anything/johndoe/world"
}

Differentiate from Plugin Metadata​

When working with plugins, it is important to understand the distinctions between the _meta common configurations, as outlined in this document, and the plugin metadata. These two concepts serve different purposes and should not be mixed.

While the _meta common configurations refer to configuration options that are available for all APISIX plugins, plugin metadata only applies to plugins that have metadata attributes. These metadata attributes could also be configured with the Admin API plugin metadata resource.

See plugin metadata to learn more.