Apache APISIX · Schema

Apache APISIX Route

A Route defines rules to match client requests and specifies how to handle matched requests, including plugins and upstream configurations.

ApacheAPI GatewayCloud NativeKubernetesLuaNGINXOpen SourceTraffic Management

Properties

Name	Type	Description
uri	string	The request URI path. Supports path prefixes with wildcard.
uris	array	A list of URIs for the route to match.
name	string	Human-readable name for the route.
desc	string	Description of the route.
host	string	Host to match for the route.
hosts	array	A list of hosts for the route to match.
methods	array	HTTP methods to match.
remote_addr	string	Client IP address to match.
remote_addrs	array	A list of client IP addresses to match.
vars	array	DSL expressions for matching request attributes.
priority	integer	Route priority for matching order. Higher value means higher priority.
plugins	object	Plugin configuration. Key is the plugin name and value is the plugin config.
upstream	object	Inline upstream configuration.
upstream_id	string	ID of an existing upstream to use.
service_id	string	ID of an existing service to bind to.
plugin_config_id	string	ID of a plugin config to bind to.
labels	object	Key-value pairs for categorization.
timeout	object	Timeout settings for upstream connections.
enable_websocket	boolean	Enable WebSocket proxying.
status	integer	Route status. 1 for enabled, 0 for disabled.
filter_func	string	A Lua function string for custom filtering logic.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/api-evangelist/apache-apisix/blob/main/json-schema/route.json",
  "title": "Apache APISIX Route",
  "description": "A Route defines rules to match client requests and specifies how to handle matched requests, including plugins and upstream configurations.",
  "type": "object",
  "properties": {
    "uri": {
      "type": "string",
      "description": "The request URI path. Supports path prefixes with wildcard."
    },
    "uris": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "A list of URIs for the route to match."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name for the route."
    },
    "desc": {
      "type": "string",
      "description": "Description of the route."
    },
    "host": {
      "type": "string",
      "description": "Host to match for the route."
    },
    "hosts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "A list of hosts for the route to match."
    },
    "methods": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "GET",
          "POST",
          "PUT",
          "DELETE",
          "PATCH",
          "HEAD",
          "OPTIONS",
          "CONNECT",
          "TRACE"
        ]
      },
      "description": "HTTP methods to match."
    },
    "remote_addr": {
      "type": "string",
      "description": "Client IP address to match."
    },
    "remote_addrs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "A list of client IP addresses to match."
    },
    "vars": {
      "type": "array",
      "description": "DSL expressions for matching request attributes."
    },
    "priority": {
      "type": "integer",
      "default": 0,
      "description": "Route priority for matching order. Higher value means higher priority."
    },
    "plugins": {
      "type": "object",
      "description": "Plugin configuration. Key is the plugin name and value is the plugin config."
    },
    "upstream": {
      "$ref": "upstream.json",
      "description": "Inline upstream configuration."
    },
    "upstream_id": {
      "type": "string",
      "description": "ID of an existing upstream to use."
    },
    "service_id": {
      "type": "string",
      "description": "ID of an existing service to bind to."
    },
    "plugin_config_id": {
      "type": "string",
      "description": "ID of a plugin config to bind to."
    },
    "labels": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Key-value pairs for categorization."
    },
    "timeout": {
      "type": "object",
      "description": "Timeout settings for upstream connections.",
      "properties": {
        "connect": {
          "type": "number",
          "default": 60,
          "description": "Connection timeout in seconds."
        },
        "send": {
          "type": "number",
          "default": 60,
          "description": "Send timeout in seconds."
        },
        "read": {
          "type": "number",
          "default": 60,
          "description": "Read timeout in seconds."
        }
      }
    },
    "enable_websocket": {
      "type": "boolean",
      "description": "Enable WebSocket proxying."
    },
    "status": {
      "type": "integer",
      "enum": [0, 1],
      "default": 1,
      "description": "Route status. 1 for enabled, 0 for disabled."
    },
    "filter_func": {
      "type": "string",
      "description": "A Lua function string for custom filtering logic."
    }
  }
}