APISIX Admin API (3.15.0)

Download OpenAPI specification:Download

APISIX Admin API is a RESTful API that allows you to create and manage APISIX resources.

Route

A route defines a path to one or more upstream services.

See Routes for more information.

Get All Routes

Get all configured routes.

query Parameters

name	string Name to query routes by.
label	string Label to query routes by.
uri	string URI to query routes by.
filter	string Example: filter=service_id%3D1 Filter expression. Supports filtering routes by `service_id` and `upstream_id`.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"createdIndex": 203,
"key": "/apisix/routes/1",
"value": {"remote_addrs": ["127.0.0.1"
],
"desc": "desc",
"name": "route-test",
"priority": 0,
"vars": [["http_user",
"==",
"ios"
]
],
"update_time": 1684490006,
"create_time": 1684490006,
"id": "1",
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"allow_degradation": false,
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"key": "remote_addr"
}
},
"status": 1,
"timeout": {"read": 3,
"connect": 3,
"send": 3
},
"uri": "/ip",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"modifiedIndex": 203
}
]
}

Create Route

Create a route with an ID generated.

Request Body schema: application/json

Any of

desc	string <= 256 characters Route description.
	string or integer Plugin configuration ID.
status	integer Default: 1 Enum: 1 0 Route status: `1` to enable, `0` to disable.
	string or integer Unique identifier for the route.
enable_websocket	boolean If true, enable WebSocket proxying for the route.
	string or integer Service ID.
methods	Array of strings unique Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE" The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.
hosts	Array of strings non-empty unique An array of hostnames for route matching.
	Array of IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) non-empty unique Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.
filter_func	string >= 10 characters ^function A user-defined function for advanced request filtering.
vars	Array of arrays Conditions in the format of APISIX expressions to match request to routes. Case sensitive when matching a cookie name.
name	string [ 1 .. 100 ] characters Route name.
	string or integer Upstream ID.
	string or integer Script ID.
host	string A single hostname for route matching.
priority	integer Default: 0 Priority of the route. A higher value corresponds to a higher priority. If different routes matches to the same URI, then the route with the highest priority will be matched.
	Use Upstream Nodes (object) or Use Service Registry (object) The upstream contains necessary information for the gateway to proxy request to the backend service.
plugins required	object Key-value pairs of plugins and their configurations on the object.
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.
	object Key-value pairs to specify attributes.
	object Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.
script	string [ 10 .. 102400 ] characters Lua script.
uri required	string [ 1 .. 4096 ] characters Single URI the route should match.
uris	Array of strings non-empty unique List of URIs the route should match.

Responses

Request samples

Payload

Content type

application/json

{"name": "route-name",
"desc": "desc",
"hosts": ["a.com",
"b.com"
],
"methods": ["GET",
"POST"
],
"uri": "/ip",
"upstream": {"type": "roundrobin",
"nodes": {"httpbin.org:80": 1
}
}
}

Response samples

201

Content type

application/json

{"value": {"desc": "desc",
"name": "route-name",
"update_time": 1684490245,
"priority": 0,
"id": "00000000000000000206",
"status": 1,
"create_time": 1684490245,
"uri": "/ip",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"key": "/apisix/routes/00000000000000000206"
}

Create Route by ID

Create a route with a custom ID.

path Parameters

id

required

string

The route ID.

Request Body schema: application/json

Any of

desc	string <= 256 characters Route description.
	string or integer Plugin configuration ID.
status	integer Default: 1 Enum: 1 0 Route status: `1` to enable, `0` to disable.
	string or integer Unique identifier for the route.
enable_websocket	boolean If true, enable WebSocket proxying for the route.
	string or integer Service ID.
methods	Array of strings unique Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE" The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.
hosts	Array of strings non-empty unique An array of hostnames for route matching.
	Array of IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) non-empty unique Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.
filter_func	string >= 10 characters ^function A user-defined function for advanced request filtering.
vars	Array of arrays Conditions in the format of APISIX expressions to match request to routes. Case sensitive when matching a cookie name.
name	string [ 1 .. 100 ] characters Route name.
	string or integer Upstream ID.
	string or integer Script ID.
host	string A single hostname for route matching.
priority	integer Default: 0 Priority of the route. A higher value corresponds to a higher priority. If different Routes matches to the same URI, then the Route with the highest priority will be matched.
	Use Upstream Nodes (object) or Use Service Registry (object) The upstream contains necessary information for the gateway to proxy request to the backend service.
plugins required	object Key-value pairs of plugins and their configurations on the object.
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.
	object Key-value pairs to specify attributes.
	object Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.
script	string [ 10 .. 102400 ] characters Lua script.
uri required	string [ 1 .. 4096 ] characters Single URI the route should match.
uris	Array of strings non-empty unique List of URIs the route should match.

Responses

Request samples

Payload

Content type

application/json

{"name": "route-test",
"desc": "desc",
"uri": "/ip",
"hosts": ["a.com",
"b.com"
],
"methods": ["GET",
"POST"
],
"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
},
"priority": 0,
"remote_addrs": ["127.0.0.1"
],
"vars": [["http_user",
"==",
"ios"
]
],
"upstream": {"type": "roundrobin",
"nodes": {"httpbin.org:80": 1
}
},
"timeout": {"connect": 3,
"send": 3,
"read": 3
}
}

Response samples

201

Content type

application/json

{"value": {"remote_addrs": ["127.0.0.1"
],
"desc": "desc",
"name": "route-test",
"priority": 0,
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"key": "remote_addr",
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"allow_degradation": false
}
},
"vars": [["http_user",
"==",
"ios"
]
],
"id": "1",
"status": 1,
"uri": "/ip",
"timeout": {"connect": 3,
"read": 3,
"send": 3
},
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"key": "/apisix/routes/1"
}

Get Route by ID

Get a route by ID.

path Parameters

id

required

string

The route ID.

Responses

Response samples

200

Content type

application/json

{"createdIndex": 203,
"key": "/apisix/routes/1",
"value": {"remote_addrs": ["127.0.0.1"
],
"desc": "desc",
"name": "route-test",
"priority": 0,
"vars": [["http_user",
"==",
"ios"
]
],
"update_time": 1684490006,
"create_time": 1684490006,
"id": "1",
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"allow_degradation": false,
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"key": "remote_addr"
}
},
"status": 1,
"timeout": {"read": 3,
"connect": 3,
"send": 3
},
"uri": "/ip",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"modifiedIndex": 203
}

Update Route

Update a route.

path Parameters

id

required

string

Example: 1

The target route ID.

Request Body schema: application/json

Any of

desc	string <= 256 characters Route description.
	string or integer Plugin configuration ID.
status	integer Default: 1 Enum: 1 0 Route status: `1` to enable, `0` to disable.
	string or integer Unique identifier for the route.
enable_websocket	boolean If true, enable WebSocket proxying for the route.
	string or integer Service ID.
methods	Array of strings unique Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE" "PURGE" The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.
hosts	Array of strings non-empty unique An array of hostnames for route matching.
	Array of IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) non-empty unique Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.
filter_func	string >= 10 characters ^function A user-defined function for advanced request filtering.
vars	Array of arrays Conditions in the format of APISIX expressions to match request to routes. Case sensitive when matching a cookie name.
name	string [ 1 .. 100 ] characters Route name.
	string or integer Upstream ID.
	string or integer Script ID.
host	string A single hostname for route matching.
priority	integer Default: 0 Priority of the route. A higher value corresponds to a higher priority. If different routes matches to the same URI, then the route with the highest priority will be matched.
	Use Upstream Nodes (object) or Use Service Registry (object) The upstream contains necessary information for the gateway to proxy request to the backend service.
plugins required	object Key-value pairs of plugins and their configurations on the object.
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.
	object Key-value pairs to specify attributes.
	object Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.
script	string [ 10 .. 102400 ] characters Lua script.
uri required	string [ 1 .. 4096 ] characters Single URI the route should match.
uris	Array of strings non-empty unique List of URIs the route should match.

Responses

Request samples

Payload

Content type

application/json

{"upstream": {"nodes": {"127.0.0.1:1981": 1
}
}
}

Response samples

200

Content type

application/json

Example

Update Upstream Node To The Route

{"value": {"remote_addrs": ["127.0.0.1"
],
"desc": "desc",
"name": "route-test",
"priority": 0,
"vars": [["http_user",
"==",
"ios"
]
],
"update_time": 1684490363,
"create_time": 1684490006,
"id": "1",
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"allow_degradation": false,
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"key": "remote_addr"
}
},
"status": 1,
"timeout": {"read": 3,
"connect": 3,
"send": 3
},
"uri": "/ip",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"httpbin.org:80": 1,
"127.0.0.1:1981": 1
},
"type": "roundrobin",
"scheme": "http"
},
"methods": ["GET",
"POST"
],
"hosts": ["a.com",
"b.com"
]
},
"key": "/apisix/routes/1"
}

Delete Route by ID

Delete a route by ID.

path Parameters

id

required

string

The route ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"deleted": "1",
"key": "/apisix/routes/1"
}

Upstream

An upstream is a logical abstraction of one or more upstream addresses.

See Upstreams for more information.

Get All Upstreams

Get all configured upstreams.

query Parameters

name	string Name to query upstreams by.
label	string Label to query upstreams by.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "1",
"create_time": 1684290697,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291419,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"httpbin.org:443": 1
},
"scheme": "https"
},
"key": "/apisix/upstreams/1",
"modifiedIndex": 126,
"createdIndex": 121
},
{"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "2",
"create_time": 1684291436,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291436,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"mock.api7.ai:443": 1
},
"scheme": "https"
},
"key": "/apisix/upstreams/2",
"modifiedIndex": 127,
"createdIndex": 127
}
],
"total": 2
}

Create Upstream

Create an upstream with an ID generated.

Request Body schema: application/json

One of

required	Weight Mapping (object) or Array of Node Objects (objects) The upstream endpoints.
desc	string <= 256 characters Upstream description.
key	string The key used with `hash_on` when `type` is `chash`. When `hash_on` is set to `header` or `cookie`, `key` is required. When `hash_on` is set to `vars` or `vars_combinations`, `key` is required and supports built-in variables. When `hash_on` is set to `consumer`, `key` is not required as the consumer name will be used as the key automatically.
retries	integer >= 0 The number of retries while passing the request to an upstream.
retry_timeout	number >= 0 Timeout to continue with retries. Setting this to `0` disables the retry timeout.
pass_host	string Default: "pass" Enum: "pass" "node" "rewrite" Configure the host when the request is forwarded to the upstream. `pass` is used to pass the request's host to the upstream without modification. `node` sets the host to the host of the upstream node. `rewrite` sets the host to the value of `upstream_host`.
upstream_host	string Value to rewrite the host header to.
type	string Default: "roundrobin" Enum: "roundrobin" "chash" "ewma" "least_conn" Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms.
	Active Check (object) or Passive Check (object) Health check configurations.
hash_on	string Default: "vars" Enum: "vars" "header" "cookie" "consumer" "vars_combinations" Type of value to hash on when `type` is `chash`.
name	string [ 1 .. 100 ] characters Upstream name.
scheme	any Default: "http" Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka" Protocol to communicate with the upstream.
	object Upstream keepalive connection pool.
	object Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.
	string or integer Upstream ID.
	object Key-value pairs to specify attributes.
	object Service discovery arguments.
	object TLS configurations.

Responses

Request samples

Payload

Content type

application/json

{"name": "upstream-for-test",
"desc": "desc",
"scheme": "http",
"retries": 1,
"type": "roundrobin",
"nodes": {"127.0.0.1:1980": 1
},
"timeout": {"connect": 15,
"send": 15,
"read": 15
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/upstreams/00000000000000000128",
"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "00000000000000000128",
"create_time": 1684291897,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291897,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"127.0.0.1:1980": 1
},
"scheme": "http"
}
}

Create an Upstream by ID

Create an upstream with a custom ID.

path Parameters

id

required

string

Specified upstream ID.

Request Body schema: application/json

One of

required	Weight Mapping (object) or Array of Node Objects (objects) The upstream endpoints.
desc	string <= 256 characters Upstream description.
key	string The key used with `hash_on` when `type` is `chash`. When `hash_on` is set to `header` or `cookie`, `key` is required. When `hash_on` is set to `vars` or `vars_combinations`, `key` is required and supports built-in variables. When `hash_on` is set to `consumer`, `key` is not required as the consumer name will be used as the key automatically.
retries	integer >= 0 The number of retries while passing the request to an upstream.
retry_timeout	number >= 0 Timeout to continue with retries. Setting this to `0` disables the retry timeout.
pass_host	string Default: "pass" Enum: "pass" "node" "rewrite" Configure the host when the request is forwarded to the upstream. `pass` is used to pass the request's host to the upstream without modification. `node` sets the host to the host of the upstream node. `rewrite` sets the host to the value of `upstream_host`.
upstream_host	string Value to rewrite the host header to.
type	string Default: "roundrobin" Enum: "roundrobin" "chash" "ewma" "least_conn" Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms.
	Active Check (object) or Passive Check (object) Health check configurations.
hash_on	string Default: "vars" Enum: "vars" "header" "cookie" "consumer" "vars_combinations" Type of value to hash on when `type` is `chash`.
name	string [ 1 .. 100 ] characters Upstream name.
scheme	any Default: "http" Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka" Protocol to communicate with the upstream.
	object Upstream keepalive connection pool.
	object Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.
	string or integer Upstream ID.
	object Key-value pairs to specify attributes.
	object Service discovery arguments.
	object TLS configurations.

Responses

Request samples

Payload

Content type

application/json

{"name": "upstream-for-test",
"desc": "desc",
"scheme": "http",
"retries": 1,
"type": "roundrobin",
"nodes": {"127.0.0.1:1980": 1
},
"timeout": {"connect": 15,
"send": 15,
"read": 15
}
}

Response samples

201

Content type

application/json

Example

Create an Upstream by ID

{"key": "/apisix/upstreams/1",
"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "1",
"create_time": 1684290697,
"retries": 1,
"pass_host": "pass",
"update_time": 1684290697,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"127.0.0.1:1980": 1
},
"scheme": "http"
}
}

Update Upstream

Update an upstream.

path Parameters

id

required

string

Specified upstream ID.

Request Body schema: application/json

One of

required	Weight Mapping (object) or Array of Node Objects (objects) The upstream endpoints.
desc	string <= 256 characters Upstream description.
key	string The key used with `hash_on` when `type` is `chash`. When `hash_on` is set to `header` or `cookie`, `key` is required. When `hash_on` is set to `vars` or `vars_combinations`, `key` is required and supports built-in variables. When `hash_on` is set to `consumer`, `key` is not required as the consumer name will be used as the key automatically.
retries	integer >= 0 The number of retries while passing the request to an upstream.
retry_timeout	number >= 0 Timeout to continue with retries. Setting this to 0 disables the retry timeout.
pass_host	string Default: "pass" Enum: "pass" "node" "rewrite" Configure the host when the request is forwarded to the upstream. `pass` is used to pass the request's host to the upstream without modification. `node` sets the host to the host of the upstream node. `rewrite` sets the host to the value of `upstream_host`.
upstream_host	string Value to rewrite the host header to.
type	string Default: "roundrobin" Enum: "roundrobin" "chash" "ewma" "least_conn" Load balancing algorithm. Support weighted round robin, consistent hashing, exponentially weighted moving average, and least connections algorithms.
	Active Check (object) or Passive Check (object) Health check configurations.
hash_on	string Default: "vars" Enum: "vars" "header" "cookie" "consumer" "vars_combinations" Type of value to hash on when `type` is `chash`.
name	string [ 1 .. 100 ] characters Upstream name.
scheme	any Default: "http" Enum: "grpc" "grpcs" "http" "https" "tcp" "tls" "udp" "kafka" Protocol to communicate with the upstream.
	object Upstream keepalive connection pool.
	object Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.
	string or integer Upstream ID.
	object Key-value pairs to specify attributes.
	object Service discovery arguments.
	object TLS configurations.

Responses

Request samples

Payload

Content type

application/json

{"nodes": {"127.0.0.1:1981": 1
}
}

Response samples

200

Content type

application/json

{"key": "/apisix/upstreams/1",
"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "1",
"create_time": 1684290697,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291001,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"127.0.0.1:1981": 1,
"127.0.0.1:1980": 1
},
"scheme": "http"
}
}

Get Upstream by ID

Get an upstream by ID.

path Parameters

id

required

string

Specified upstream ID.

Responses

Response samples

200

Content type

application/json

{"value": {"timeout": {"send": 15,
"read": 15,
"connect": 15
},
"desc": "desc",
"id": "1",
"create_time": 1684290697,
"retries": 1,
"pass_host": "pass",
"update_time": 1684291419,
"type": "roundrobin",
"name": "upstream-for-test",
"hash_on": "vars",
"nodes": {"httpbin.org:443": 1
},
"scheme": "https"
},
"key": "/apisix/upstreams/1",
"modifiedIndex": 126,
"createdIndex": 121
}

Delete Upstream by ID

Delete an upstream by ID.

path Parameters

id

required

string

Specified upstream ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/upstreams/1",
"deleted": "1"
}

Service

A service is a backend application providing a set of functionalities.

See Services for more information.

Get All Services

Get all configured services.

query Parameters

name	string Name to query services by.
label	string Label to query services by.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"createdIndex": 117,
"key": "/apisix/services/1",
"value": {"enable_websocket": true,
"name": "service-test",
"update_time": 1684288908,
"create_time": 1684287870,
"id": "1",
"desc": "hello world",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1980": 1
},
"type": "roundrobin",
"scheme": "http"
},
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"key": "remote_addr",
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"allow_degradation": false
}
},
"hosts": ["foo.com"
]
},
"modifiedIndex": 118
}
]
}

Create Service

Create a service with an ID generated.

Request Body schema: application/json

desc	string <= 256 characters Service description.
name	string [ 1 .. 100 ] characters Service name.
	string or integer Upstream ID.
plugins	object Key-value pairs of plugins and their configurations on the object.
	Use Upstream Nodes (object) or Use Service Registry (object) The upstream contains necessary information for the gateway to proxy request to the backend service.
labels	object Key-value pairs to specify attributes.
enable_websocket	boolean If true, enable WebSocket proxying for the service.
script	string [ 10 .. 102400 ] characters Lua script.
	string or integer Unique identifier for the service.
hosts	Array of strings non-empty unique The hosts of the service to accept incoming requests.

Responses

Request samples

Payload

Content type

application/json

{"plugins": { },
"upstream": {"type": "roundrobin",
"nodes": {"127.0.0.1:1980": 1
}
},
"name": "service-test",
"desc": "hello world",
"enable_websocket": true,
"hosts": ["foo.com"
]
}

Response samples

201

Content type

application/json

{"value": {"enable_websocket": true,
"name": "service-test",
"update_time": 1684491069,
"create_time": 1684491069,
"plugins": { },
"id": "00000000000000000218",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1980": 1
},
"type": "roundrobin",
"scheme": "http"
},
"desc": "hello world",
"hosts": ["foo.com"
]
},
"key": "/apisix/services/00000000000000000218"
}

Get Service by ID

Get a service by ID.

path Parameters

id

required

string

The target service ID.

Responses

Response samples

200

Content type

application/json

{"createdIndex": 117,
"key": "/apisix/services/1",
"value": {"enable_websocket": true,
"name": "service-test",
"update_time": 1684490934,
"create_time": 1684287870,
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"allow_degradation": false,
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"key": "remote_addr"
}
},
"desc": "hello world",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1980": 1
},
"type": "roundrobin",
"scheme": "http"
},
"id": "1",
"hosts": ["foo.com"
]
},
"modifiedIndex": 216
}

Create Service by ID

Create a service with a custom ID.

path Parameters

id

required

string

Unique identifier for the service.

Request Body schema: application/json

desc	string <= 256 characters Service description.
name	string [ 1 .. 100 ] characters Service name.
	string or integer Upstream ID.
plugins	object Key-value pairs of plugins and their configurations on the object.
	Use Upstream Nodes (object) or Use Service Registry (object) The upstream contains necessary information for the gateway to proxy request to the backend service.
labels	object Key-value pairs to specify attributes.
enable_websocket	boolean If true, enable WebSocket proxying for the route that uses this service.
script	string [ 10 .. 102400 ] characters Lua script.
hosts	Array of strings non-empty unique The hosts of the service to accept incoming requests.

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
},
"upstream": {"type": "roundrobin",
"nodes": {"127.0.0.1:1980": 1
}
},
"name": "service-test",
"desc": "hello world",
"enable_websocket": true,
"hosts": ["foo.com"
]
}

Response samples

201

Content type

application/json

{"value": {"desc": "hello world",
"name": "service-test",
"update_time": 1684491005,
"create_time": 1684287870,
"plugins": {"limit-count": {"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"key": "remote_addr",
"rejected_code": 503,
"time_window": 60,
"key_type": "var",
"allow_degradation": false
}
},
"id": "1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1980": 1
},
"type": "roundrobin",
"scheme": "http"
},
"enable_websocket": true,
"hosts": ["foo.com"
]
},
"key": "/apisix/services/1"
}

Update Service

Update a service.

path Parameters

id

required

string

The target service ID.

Request Body schema: application/json

desc	string <= 256 characters Service description.
name	string [ 1 .. 100 ] characters Service name.
	string or integer Upstream ID.
plugins	object Key-value pairs of plugins and their configurations on the object.
	Use Upstream Nodes (object) or Use Service Registry (object) The upstream contains necessary information for the gateway to proxy request to the backend service.
labels	object Key-value pairs to specify attributes.
enable_websocket	boolean If true, enable WebSocket proxying for the route that uses this service.
script	string [ 10 .. 102400 ] characters Lua script.
	string or integer Unique identifier for the service.
hosts	Array of strings non-empty unique The hosts of the service to accept incoming requests.

Responses

Request samples

Payload

Content type

application/json

{"upstream": {"nodes": {"127.0.0.1:1981": 1
}
}
}

Response samples

200

Content type

application/json

{"value": {"upstream": {"scheme": "http",
"nodes": {"127.0.0.1:1981": 1,
"127.0.0.1:1980": 1
},
"type": "roundrobin",
"hash_on": "vars",
"pass_host": "pass"
},
"create_time": 1684142130,
"enable_websocket": true,
"id": "1",
"update_time": 1684142459,
"hosts": ["foo.com"
],
"name": "service-test",
"plugins": { },
"desc": "hello world"
},
"key": "/apisix/services/1"
}

Delete Service by ID

Delete a service by ID.

path Parameters

id

required

string

The service ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"deleted": "1",
"key": "/apisix/services/1"
}

Consumer

A consumer represents a user, application, or host that sends requests to the API gateway and consumes backend services.

See Consumers for more information.

Create Consumer

Create a consumer with a custom ID.

Request Body schema: application/json

plugins	object Key-value pairs of plugins and their configurations on the object.
username required	string [ 1 .. 100 ] characters ^[a-zA-Z0-9_-]+$ The unique identifier of the consumer.
labels	object Key-value pairs to specify attributes.
desc	string <= 256 characters Consumer description.
	string or integer Consumer group ID.

Responses

Request samples

Payload

Content type

application/json

{"username": "jack",
"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/consumers/jack",
"value": {"plugins": {"limit-count": {"time_window": 60,
"rejected_code": 503,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"show_limit_quota_header": true,
"allow_degradation": false,
"policy": "local"
}
},
"username": "jack",
"create_time": 1683164776,
"update_time": 1684289832
}
}

Get All Consumers

Get all configured consumers.

query Parameters

label

string

Label to query consumers by.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"username": "jack",
"create_time": 1683164776,
"update_time": 1684289832
},
"key": "/apisix/consumers/jack",
"modifiedIndex": 119,
"createdIndex": 17
}
],
"total": 1
}

Get Consumer by ID

Get a consumer by ID.

path Parameters

username

required

string

Specified consumer username.

Responses

Response samples

200

Content type

application/json

{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"username": "jack",
"create_time": 1683164776,
"update_time": 1684289832
},
"key": "/apisix/consumers/jack",
"modifiedIndex": 119,
"createdIndex": 17
}

Delete Consumer by ID

Delete a consumer by ID.

path Parameters

username

required

string

Specified consumer username.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/consumers/jack",
"deleted": "1"
}

Consumer Group

A consumer group is a group of consumers sharing the same plugin configurations.

See Consumer Groups for more information.

Get All Consumer Group

Get all configured consumer groups.

query Parameters

name	string Name to query consumer groups by.
label	string Label to query consumer groups by.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"plugins": {"limit-count": {"allow_degradation": false,
"count": 2,
"group": "consumer_group_name",
"time_window": 60,
"show_limit_quota_header": true,
"key": "remote_addr",
"rejected_code": 503,
"key_type": "var",
"policy": "local"
}
},
"desc": "desc",
"id": "company_a",
"create_time": 1684377809,
"update_time": 1684378459
},
"key": "/apisix/consumer_groups/company_a",
"modifiedIndex": 144,
"createdIndex": 143
}
],
"total": 1
}

Create Consumer Group by ID

Create a consumer group with a custom ID.

path Parameters

id

required

string

Specified consumer group ID.

Request Body schema: application/json

plugins required	object Key-value pairs of plugins and their configurations.
desc	string <= 256 characters Consumer group description.
labels	object Key-value pairs to specify attributes.
name	string [ 1 .. 100 ] characters Consumer group name.

Responses

Request samples

Payload

Content type

application/json

{"desc": "desc",
"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr",
"group": "consumer_group_name"
}
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/consumer_groups/company_a",
"value": {"plugins": {"limit-count": {"allow_degradation": false,
"count": 2,
"group": "company_a",
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"show_limit_quota_header": true,
"rejected_code": 503,
"policy": "local"
}
},
"desc": "desc",
"id": "company_a",
"create_time": 1684377809,
"update_time": 1684378459
}
}

Get Consumer Group by ID

Get a consumer group by ID.

path Parameters

id

required

string

Specified consumer group ID.

Responses

Response samples

200

Content type

application/json

{"value": {"plugins": {"limit-count": {"allow_degradation": false,
"count": 2,
"group": "consumer_group_name",
"time_window": 60,
"show_limit_quota_header": true,
"key": "remote_addr",
"rejected_code": 503,
"key_type": "var",
"policy": "local"
}
},
"desc": "desc",
"id": "company_a",
"create_time": 1684377809,
"update_time": 1684378459
},
"key": "/apisix/consumer_groups/company_a",
"modifiedIndex": 144,
"createdIndex": 143
}

Update Consumer Group

Update a consumer group.

path Parameters

id

required

string

Specified consumer group ID.

Request Body schema: application/json

plugins required	object Key-value pairs of plugins and their configurations.
desc	string <= 256 characters Consumer group description.
labels	object Key-value pairs to specify attributes.
required	string or integer Consumer group ID.

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"prometheus": { }
}
}

Response samples

200

Content type

application/json

{"key": "/apisix/consumer_groups/company_a",
"value": {"plugins": {"limit-count": {"allow_degradation": false,
"count": 2,
"group": "consumer_group_name",
"time_window": 60,
"show_limit_quota_header": true,
"key": "remote_addr",
"rejected_code": 503,
"key_type": "var",
"policy": "local"
},
"prometheus": {"prefer_name": false
}
},
"desc": "desc",
"id": "company_a",
"create_time": 1684377809,
"update_time": 1684379208
}
}

Delete Consumer Group by ID

Delete a consumer group by ID.

path Parameters

id

required

string

Specified consumer group ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/consumer_groups/company_a",
"deleted": "1"
}

Credentials

A credential is an entity used to store authentication configurations associated with consumers.

See Credentials for more information.

Get All Credentials of a Consumer

Get all configured credentials of a consumer.

path Parameters

consumer

required

string

Example: john

Specified consumer username.

query Parameters

name	string Name to query credentials by.
label	string Label to query credentials by.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"total": 2,
"list": [{"key": "/apisix/consumers/john/credentials/cred-john-basic-auth",
"value": {"update_time": 1725991703,
"id": "cred-john-basic-auth",
"plugins": {"basic-auth": {"password": "john-pass",
"username": "john-key"
}
},
"create_time": 1725991529
},
"createdIndex": 42,
"modifiedIndex": 44
},
{"key": "/apisix/consumers/john/credentials/cred-john-key-auth",
"value": {"update_time": 1725991703,
"id": "cred-john-key-auth",
"plugins": {"key-auth": {"key": "john-key"
}
},
"create_time": 1725991703
},
"createdIndex": 43,
"modifiedIndex": 43
}
]
}
]
}

Get Credential by ID

Get credential of a consumer by ID.

path Parameters

consumer required	string Example: john Specified consumer username.
id required	string Example: john-key-auth-cred Specified credential ID.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"key": "/apisix/consumers/john/credentials/cred-john-basic-auth",
"value": {"update_time": 1725991529,
"id": "cred-john-basic-auth",
"plugins": {"basic-auth": {"password": "john-pass",
"username": "john-key"
}
},
"create_time": 1725991529
},
"createdIndex": 42,
"modifiedIndex": 42
}
]
}

Create Credential by ID

Create a credential by ID.

path Parameters

consumer required	string Example: john Specified consumer username.
id required	string Example: john-key-auth-cred Specified credential ID.

Request Body schema: application/json

plugins	object `basic-auth`, `key-auth`, `hmac-auth` or `jwt-auth` configurations.
label	object Key-value pairs of custom labels. When the `custom_id` label is set and if a request is authenticated, the value will be forwarded to the upstream service in the `X-Custom-ID` header.
name	string [ 1 .. 100 ] characters Consumer credential name.
desc	string <= 256 characters Description for the credential.

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"key-auth": {"key": "john-key"
}
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/consumers/john/credentials/cred-john-key-auth",
"value": {"create_time": 1725991703,
"id": "cred-john-key-auth",
"plugins": {"key-auth": {"key": "john-key"
}
},
"update_time": 1725991703
}
}

Delete Credential by ID

Delete a credential by ID.

path Parameters

consumer required	string Example: john Specified consumer username.
id required	string Example: john-key-auth-cred Specified credential ID.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/consumers/john/credentials/cred-john-key-auth",
"deleted": "1"
}

Plugin

Plugins extend base functionalities of APISIX to meet user-specific requirements.

See Plugins for more information.

Get All Plugin Names

Get all configured plugin names.

query Parameters

subsystem

string

Default: "http"

Enum: "http" "stream"

Example: subsystem=stream

The plugin subsystem to query.

Responses

Response samples

200

Content type

application/json

["real-ip",
"ai",
"client-control",
"proxy-control",
"request-id",
"zipkin",
"ext-plugin-pre-req",
"fault-injection",
"mocking",
"serverless-pre-function",
"cors",
"ip-restriction",
"ua-restriction",
"referer-restriction",
"csrf",
"uri-blocker",
"request-validation",
"openid-connect",
"cas-auth",
"authz-casbin",
"authz-casdoor",
"wolf-rbac",
"ldap-auth",
"hmac-auth",
"basic-auth",
"jwt-auth",
"key-auth",
"consumer-restriction",
"forward-auth",
"opa",
"authz-keycloak",
"body-transformer",
"proxy-mirror",
"proxy-cache",
"proxy-rewrite",
"workflow",
"api-breaker",
"limit-conn",
"limit-count",
"limit-req",
"gzip",
"server-info",
"traffic-split",
"redirect",
"response-rewrite",
"degraphql",
"kafka-proxy",
"grpc-transcode",
"grpc-web",
"public-api",
"prometheus",
"datadog",
"elasticsearch-logger",
"echo",
"loggly",
"http-logger",
"splunk-hec-logging",
"skywalking-logger",
"google-cloud-logging",
"sls-logger",
"tcp-logger",
"kafka-logger",
"rocketmq-logger",
"syslog",
"udp-logger",
"file-logger",
"clickhouse-logger",
"tencent-cloud-cls",
"inspect",
"example-plugin",
"aws-lambda",
"azure-functions",
"openwhisk",
"openfunction",
"serverless-post-function",
"ext-plugin-post-req",
"ext-plugin-post-resp"
]

Get Plugin Attributes by Name

Get attributes of a plugin by plugin name.

path Parameters

plugin_name

required

string

The specified plugin name.

query Parameters

subsystem

string

Default: "http"

Enum: "http" "stream"

Example: subsystem=stream

The plugin subsystem to query.

Responses

Response samples

200

Content type

application/json

{"$comment": "this is a mark for our injected plugin schema.",
"type": "object",
"required": ["count",
"time_window"
],
"properties": {"_meta": {"description": "Metadata configuration for the plugin.",
"type": "object",
"additionalProperties": false,
"properties": {"disable": {"description": "If set to true, disables the plugin execution.",
"type": "boolean"
},
"error_response": {"description": "Custom error response when the plugin rejects a request.",
"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"filter": {"description": "Filter determines whether the plugin needs to be executed at runtime.",
"type": "array"
},
"pre_function": {"description": "Function to be executed before plugin execution with access to conf and ctx parameters.",
"type": "string"
},
"priority": {"description": "Priority of plugins by customized order.",
"type": "integer"
}
}
},
"allow_degradation": {"description": "If set to true, enables degradation when the rate limiting backend is unavailable.",
"type": "boolean",
"default": false
},
"count": {"description": "Maximum number of requests allowed within the time window.",
"type": "integer",
"exclusiveMinimum": 0
},
"group": {"description": "Group identifier for the rate limiting configuration.",
"type": "string"
},
"key": {"description": "Key to use for rate limiting identification.",
"type": "string",
"default": "remote_addr"
},
"key_type": {"description": "Type of the key used for rate limiting.",
"type": "string",
"enum": ["var",
"var_combination",
"constant"
],
"default": "var"
},
"policy": {"description": "Policy for rate limiting behavior.",
"type": "string",
"enum": ["local",
"redis",
"redis-cluster"
],
"default": "local"
},
"rejected_code": {"description": "HTTP status code returned when requests exceed the limit.",
"type": "integer",
"default": 503,
"minimum": 200,
"maximum": 599
},
"rejected_msg": {"description": "Custom message returned when requests exceed the limit.",
"type": "string",
"minLength": 1
},
"show_limit_quota_header": {"description": "If set to true, adds X-RateLimit-Limit and X-RateLimit-Remaining headers to responses.",
"type": "boolean",
"default": true
},
"time_window": {"description": "Time window in seconds for rate limiting.",
"type": "integer",
"exclusiveMinimum": 0
}
},
"if": {"properties": {"policy": {"enum": ["redis"
]
}
}
},
"then": {"properties": {"redis_database": {"description": "Redis database index.",
"type": "integer",
"default": 0,
"minimum": 0
},
"redis_host": {"description": "Redis server host address.",
"type": "string",
"minLength": 2
},
"redis_password": {"description": "Password for Redis authentication.",
"type": "string",
"minLength": 0
},
"redis_port": {"description": "Redis server port.",
"type": "integer",
"default": 6379,
"minimum": 1
},
"redis_ssl": {"description": "If set to true, enables SSL encryption for Redis connections.",
"type": "boolean",
"default": false
},
"redis_ssl_verify": {"description": "If set to true, verifies SSL certificates for Redis connections.",
"type": "boolean",
"default": false
},
"redis_timeout": {"description": "Timeout in milliseconds for Redis operations.",
"type": "integer",
"default": 1000,
"minimum": 1
},
"redis_username": {"description": "Username for Redis authentication.",
"type": "string",
"minLength": 1
}
},
"required": ["redis_host"
]
},
"else": {"if": {"properties": {"policy": {"enum": ["redis-cluster"
]
}
}
},
"then": {"properties": {"redis_cluster_name": {"description": "Name of the Redis cluster.",
"type": "string"
},
"redis_cluster_nodes": {"description": "List of Redis cluster node addresses.",
"type": "array",
"minItems": 1,
"items": {"type": "string",
"minLength": 2,
"maxLength": 100
}
},
"redis_cluster_ssl": {"description": "If set to true, enables SSL encryption for Redis cluster connections.",
"type": "boolean",
"default": false
},
"redis_cluster_ssl_verify": {"description": "If set to true, verifies SSL certificates for Redis cluster connections.",
"type": "boolean",
"default": false
},
"redis_password": {"description": "Password for Redis cluster authentication.",
"type": "string",
"minLength": 0
},
"redis_timeout": {"description": "Timeout in milliseconds for Redis cluster operations.",
"type": "integer",
"default": 1000,
"minimum": 1
}
},
"required": ["redis_cluster_nodes",
"redis_cluster_name"
]
}
}
}

Get All Plugin Attributes

Get all configured plugin attributes. This API is being deprecated soon.

query Parameters

all required	string Example: all=true Get all plugin attributes.
subsystem	string Default: "http" Enum: "http" "stream" Example: subsystem=stream The plugin subsystem to query.

Responses

Response samples

200

Content type

application/json

{"limit-conn": {"priority": 1003,
"version": 0.1,
"schema": {"type": "object",
"$comment": "this is a mark for our injected plugin schema",
"required": ["conn",
"burst",
"default_conn_delay",
"key"
],
"properties": {"only_use_default_delay": {"type": "boolean",
"default": false
},
"conn": {"type": "integer",
"exclusiveMinimum": 0
},
"burst": {"type": "integer",
"minimum": 0
},
"key_type": {"type": "string",
"enum": ["var",
"var_combination"
],
"default": "var"
},
"_meta": {"type": "object",
"properties": {"filter": {"type": "array",
"description": "filter determines whether the plugin needs to be executed at runtime"
},
"error_response": {"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"priority": {"type": "integer",
"description": "priority of plugins by customized order"
},
"disable": {"type": "boolean"
}
}
},
"key": {"type": "string"
},
"default_conn_delay": {"type": "number",
"exclusiveMinimum": 0
}
}
}
},
"syslog": {"schema": {"type": "object",
"$comment": "this is a mark for our injected plugin schema",
"required": ["host",
"port"
],
"properties": {"_meta": {"type": "object",
"properties": {"filter": {"type": "array",
"description": "filter determines whether the plugin needs to be executed at runtime"
},
"error_response": {"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"priority": {"type": "integer",
"description": "priority of plugins by customized order"
},
"disable": {"type": "boolean"
}
}
},
"host": {"type": "string"
},
"max_retry_count": {"type": "integer",
"default": 0,
"minimum": 0
},
"drop_limit": {"type": "integer",
"default": 1048576
},
"flush_limit": {"type": "integer",
"default": 4096,
"minimum": 1
},
"pool_size": {"type": "integer",
"default": 5,
"minimum": 5
},
"sock_type": {"type": "string",
"default": "tcp",
"enum": ["tcp",
"udp"
]
},
"buffer_duration": {"type": "integer",
"default": 60,
"minimum": 1
},
"retry_delay": {"type": "integer",
"default": 1,
"minimum": 0
},
"tls": {"type": "boolean",
"default": false
},
"name": {"type": "string",
"default": "stream sys logger"
},
"log_format": {"type": "object"
},
"batch_max_size": {"type": "integer",
"default": 1000,
"minimum": 1
},
"timeout": {"type": "integer",
"default": 3000,
"minimum": 1
},
"inactive_timeout": {"type": "integer",
"default": 5,
"minimum": 1
},
"port": {"type": "integer"
}
}
},
"priority": 401,
"version": 0.1,
"metadata_schema": {"type": "object",
"properties": {"log_format": {"type": "object",
"default": {"@timestamp": "$time_iso8601",
"host": "$host",
"client_ip": "$remote_addr"
}
}
}
}
},
"ip-restriction": {"priority": 3000,
"version": 0.1,
"schema": {"type": "object",
"oneOf": [{"required": ["whitelist"
]
},
{"required": ["blacklist"
]
}
],
"$comment": "this is a mark for our injected plugin schema",
"properties": {"message": {"type": "string",
"minLength": 1,
"maxLength": 1024,
"default": "Your IP address is not allowed"
},
"_meta": {"type": "object",
"properties": {"filter": {"type": "array",
"description": "filter determines whether the plugin needs to be executed at runtime"
},
"error_response": {"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"priority": {"type": "integer",
"description": "priority of plugins by customized order"
},
"disable": {"type": "boolean"
}
}
},
"blacklist": {"type": "array",
"minItems": 1,
"items": {"anyOf": [{"type": "string",
"format": "ipv4",
"title": "IPv4"
},
{"type": "string",
"pattern": "^([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])/([12]?[0-9]|3[0-2])$",
"title": "IPv4/CIDR"
},
{"type": "string",
"format": "ipv6",
"title": "IPv6"
},
{"type": "string",
"pattern": "^([a-fA-F0-9]{0,4}:){1,8}(:[a-fA-F0-9]{0,4}){0,8}([a-fA-F0-9]{0,4})?/[0-9]{1,3}$",
"title": "IPv6/CIDR"
}
]
}
},
"whitelist": {"type": "array",
"minItems": 1,
"items": {"anyOf": [{"type": "string",
"format": "ipv4",
"title": "IPv4"
},
{"type": "string",
"pattern": "^([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])/([12]?[0-9]|3[0-2])$",
"title": "IPv4/CIDR"
},
{"type": "string",
"format": "ipv6",
"title": "IPv6"
},
{"type": "string",
"pattern": "^([a-fA-F0-9]{0,4}:){1,8}(:[a-fA-F0-9]{0,4}){0,8}([a-fA-F0-9]{0,4})?/[0-9]{1,3}$",
"title": "IPv6/CIDR"
}
]
}
}
}
}
},
"mqtt-proxy": {"priority": 1000,
"version": 0.1,
"schema": {"type": "object",
"$comment": "this is a mark for our injected plugin schema",
"required": ["protocol_name",
"protocol_level"
],
"properties": {"_meta": {"type": "object",
"properties": {"filter": {"type": "array",
"description": "filter determines whether the plugin needs to be executed at runtime"
},
"error_response": {"oneOf": [{"type": "string"
},
{"type": "object"
}
]
},
"priority": {"type": "integer",
"description": "priority of plugins by customized order"
},
"disable": {"type": "boolean"
}
}
},
"protocol_name": {"type": "string"
},
"protocol_level": {"type": "integer"
}
}
}
}
}

Reload All Plugins

Hot reload all plugins for changes to the plugin source files to take effect.

Responses

Response samples

200

Content type

application/json

"done"

Plugin Config

Plugin config is used to configure plugin configurations that can be shared among other objects, such as routes.

See Plugin Configs for more information.

Get All Plugin Configs

Get all configured plugin configs.

query Parameters

name	string Name to query plugin configs by.
label	string Label to query plugin configs by.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"desc": "desc",
"id": "1",
"create_time": 1684380007,
"update_time": 1684380034
},
"key": "/apisix/plugin_configs/1",
"modifiedIndex": 151,
"createdIndex": 150
}
],
"total": 1
}

Create Plugin Config by ID

Create a plugin config with a custom ID.

path Parameters

id

required

integer

Example: 1

Specified plugin config ID.

Request Body schema: application/json

plugins	object Key-value pairs of plugins and their configurations on the service.
desc	string <= 256 characters Plugin configration description.
labels	object Key-value pairs to specify attributes.
	string or integer Plugin configration ID.

Responses

Request samples

Payload

Content type

application/json

{"desc": "desc",
"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/plugin_configs/1",
"value": {"plugins": {"limit-count": {"time_window": 60,
"rejected_code": 503,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"show_limit_quota_header": true,
"allow_degradation": false,
"policy": "local"
}
},
"desc": "desc",
"id": "1",
"create_time": 1684380007,
"update_time": 1684380034
}
}

Get Plugin Config by ID

Get a plugin config by ID.

path Parameters

id

required

string

Specified plugin config ID.

Responses

Response samples

200

Content type

application/json

{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"desc": "desc",
"id": "1",
"create_time": 1684380007,
"update_time": 1684380034
},
"key": "/apisix/plugin_configs/1",
"modifiedIndex": 151,
"createdIndex": 150
}

Update Plugin Config

Update a plugin config.

path Parameters

id

required

string

Specified plugin config ID.

Request Body schema: application/json

plugins	object Key-value pairs of plugins and their configurations on the service.
desc	string <= 256 characters Plugin configration description.
labels	object Key-value pairs to specify attributes.
	string or integer Plugin configration ID.

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"prometheus": { }
}
}

Response samples

200

Content type

application/json

{"key": "/apisix/plugin_configs/1",
"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
},
"prometheus": {"prefer_name": false
}
},
"desc": "desc",
"id": "1",
"create_time": 1684380007,
"update_time": 1684380472
}
}

Delete Plugin Config by ID

Delete a plugin config by ID.

path Parameters

id

required

string

Specified plugin config ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/plugin_configs/1",
"deleted": "1"
}

Plugin Metadata

Plugin metadata is used to configure the common metadata field(s) of all plugin instances sharing the same plugin name.

See Plugin Metadata for more information.

Get All Plugin Metadata

Get all plugin metadata.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"log_format": {"host": "$host",
"@timestamp": "$time_iso8601",
"client_ip": "$remote_addr"
}
},
"key": "/apisix/plugin_metadata/syslog",
"modifiedIndex": 283,
"createdIndex": 283
}
],
"total": 1
}

Create Plugin Metadata by Name

Create a plugin metadata by plugin name.

path Parameters

plugin_name

required

string

The specified plugin name.

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"log_format": {"host": "$host",
"@timestamp": "$time_iso8601",
"client_ip": "$remote_addr"
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/plugin_metadata/syslog",
"value": {"log_format": {"host": "$host",
"@timestamp": "$time_iso8601",
"client_ip": "$remote_addr"
}
}
}

Get Plugin Metadata by Name

Get plugin metadata by plugin name.

path Parameters

plugin_name

required

string

The specified plugin name.

Responses

Response samples

200

Content type

application/json

{"value": {"log_format": {"host": "$host",
"@timestamp": "$time_iso8601",
"client_ip": "$remote_addr"
}
},
"key": "/apisix/plugin_metadata/syslog",
"modifiedIndex": 156,
"createdIndex": 156
}

Delete Plugin Metadata by Name

Delete a plugin metadata by plugin name.

path Parameters

plugin_name

required

string

The specified plugin name.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/plugin_metadata/syslog",
"deleted": "1"
}

Global Rule

A plugin global rule is used to create plugins that are triggered on every incoming request and executed before other plugins locally bound to objects, such as routes, services, consumers, consumer groups, or plugin configs.

See Global Rules for more information.

Get All Global Rules

Get all configured plugin global rules.

query Parameters

name	string Name to query global rules by.
label	string Label to query global rules by.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"update_time": 1684375502,
"create_time": 1684375502,
"id": "1"
},
"key": "/apisix/global_rules/1",
"modifiedIndex": 137,
"createdIndex": 137
}
],
"total": 1
}

Create Global Rule by ID

Create a plugin global rule with a custom ID.

path Parameters

id

required

string

Specified global rule ID.

Request Body schema: application/json

required	string or integer Specified global rule ID.
plugins required	object Key-value pairs of plugins and their configurations.

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"limit-count": {"count": 2,
"time_window": 60,
"rejected_code": 503,
"key": "remote_addr"
}
}
}

Response samples

201

Content type

application/json

{"key": "/apisix/global_rules/1",
"value": {"plugins": {"limit-count": {"time_window": 60,
"rejected_code": 503,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"show_limit_quota_header": true,
"allow_degradation": false,
"policy": "local"
}
},
"id": "1",
"create_time": 1684375502,
"update_time": 1684375502
}
}

Get Global Rule by ID

Get a global rule by ID.

path Parameters

id

required

string

Specified global rule ID.

Responses

Response samples

200

Content type

application/json

{"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 2,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"update_time": 1684375502,
"create_time": 1684375502,
"id": "1"
},
"key": "/apisix/global_rules/1",
"modifiedIndex": 137,
"createdIndex": 137
}

Update Global Rule

Update a plugin global rule.

path Parameters

id

required

string

Specified global rule ID.

Request Body schema: application/json

	string or integer Specified global rule ID.
plugins	object Key-value pairs of plugins and their configurations.

Responses

Request samples

Payload

Content type

application/json

{"plugins": {"limit-count": {"count": 3
}
}
}

Response samples

200

Content type

application/json

{"key": "/apisix/global_rules/1",
"value": {"plugins": {"limit-count": {"rejected_code": 503,
"time_window": 60,
"key": "remote_addr",
"key_type": "var",
"count": 3,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local"
}
},
"update_time": 1684376614,
"create_time": 1684375502,
"id": "1"
}
}

Delete Global Rule by ID

Delete a plugin global rule by ID.

path Parameters

id

required

string

Specified global rule ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/global_rules/1",
"deleted": "1"
}

Stream Route

A stream route defines a path to one or more upstream services when APISIX functions as a stream proxy that operates on the transport layer for TCP and UDP connections.

See Stream Routes for more information.

Get All Stream Routes

Get all configured stream routes.

query Parameters

name	string Name to query stream routes by.
label	string Label to query stream routes by.
filter	string Example: filter=service_id%3D1 Filter expression. Supports filtering stream routes by `service_id` and `upstream_id`.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"createdIndex": 173,
"key": "/apisix/stream_routes/1",
"value": {"id": "1",
"create_time": 1684392990,
"server_addr": "127.0.0.1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin",
"scheme": "http"
},
"update_time": 1684392990,
"server_port": 2000
},
"modifiedIndex": 173
}
]
}

Create Stream Route

Create a stream route with an ID generated.

Request Body schema: application/json

desc	string <= 256 characters Description of the stream route.
name	string [ 1 .. 100 ] characters Stream route name.
label	object Key-value pairs of custom labels.
	string or integer Upstream ID.
	string or integer Service ID.
sni	string The SNI hostname for matching the TLS passthrough routing.
	string or integer Unique identifier for the stream route.
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.
	object Protocol configuration for the stream route.
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) Server IP address.
	Use Upstream Nodes (object) or Use Service Registry (object) Upstream configuration for the stream route.
plugins	object Key-value pairs of plugins and their configurations on the object.
server_port	integer Server port.

Responses

Request samples

Payload

Content type

application/json

{"server_addr": "127.0.0.1",
"server_port": 2000,
"upstream": {"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin"
}
}

Response samples

201

Content type

application/json

{"value": {"id": "00000000000000000176",
"create_time": 1684393167,
"server_addr": "127.0.0.1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin",
"scheme": "http"
},
"update_time": 1684393167,
"server_port": 2000
},
"key": "/apisix/stream_routes/00000000000000000176"
}

Get Stream Route by ID

Get stream route by ID.

path Parameters

id

required

string

Specified stream route ID.

Responses

Response samples

200

Content type

application/json

{"id": "1",
"create_time": 1684392990,
"server_addr": "127.0.0.1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin",
"scheme": "http"
},
"update_time": 1684392990,
"server_port": 2000
}

Create Stream Route by ID

Create a stream route with a specified ID.

path Parameters

id

required

string

Specified stream route ID.

Request Body schema: application/json

name	string [ 1 .. 100 ] characters Stream route name.
label	object Key-value pairs of custom labels.
desc	string <= 256 characters Description of the stream route.
	string or integer Upstream ID.
	string or integer Service ID.
sni	string The SNI hostname for matching the TLS passthrough routing.
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.
	object Protocol configuration for the stream route.
	IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string) Server IP address.
	Use Upstream Nodes (object) or Use Service Registry (object) Upstream configuration for the stream route.
plugins	object Key-value pairs of plugins and their configurations on the object.
server_port	integer Server port.

Responses

Request samples

Payload

Content type

application/json

{"server_addr": "127.0.0.1",
"server_port": 2000,
"upstream": {"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin"
}
}

Response samples

201

Content type

application/json

{"value": {"id": "00000000000000000176",
"create_time": 1684393167,
"server_addr": "127.0.0.1",
"upstream": {"hash_on": "vars",
"pass_host": "pass",
"nodes": {"127.0.0.1:1995": 1
},
"type": "roundrobin",
"scheme": "http"
},
"update_time": 1684393167,
"server_port": 2000
},
"key": "/apisix/stream_routes/00000000000000000176"
}

Delete Stream Route by ID

Delete a stream route by ID.

path Parameters

id

required

string

Specified stream route ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"deleted": "1",
"key": "/apisix/stream_routes/1"
}

SSL

An SSL certificate in Admin API is required to configure TLS or mTLS with client applications and configure mTLS with upstream services.

See SSL for more information.

Get All SSL

Get all configured SSL.

query Parameters

label

string

Label to query SSL by.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"type": "server",
"key": "<content of server.key>",
"snis": ["test.com"
],
"id": "1",
"create_time": 1684373523,
"status": 1,
"cert": "<content of server.crt>",
"update_time": 1684373523
},
"key": "/apisix/ssls/1",
"modifiedIndex": 133,
"createdIndex": 133
}
],
"total": 1
}

Create SSL

Create an SSL with an ID generated.

Request Body schema: application/json

One of

labels	object Key-value pairs to specify attributes.
desc	string <= 256 characters SSL description.
status	integer Default: 1 Enum: 1 0 SSL status. Set to `1` to enable and `0` to disable.
keys	Array of strings[ items [ 128 .. 65536 ] characters ] An array of private key content or reference to private key content.
key required	string [ 128 .. 65536 ] characters A private key content or reference to private key content.
sni required	string The SNI hostname for matching the SSL certificate.
	string or integer Specified SSL ID.
	object Client certificate.
certs	Array of strings[ items [ 128 .. 65536 ] characters ] An array of certificate content or reference to the certificate content.
type	string Default: "server" Enum: "server" "client" APISIX acts as an SSL server or client.
cert required	string [ 128 .. 65536 ] characters Certificate content or reference to the certificate content.
snis	Array of strings non-empty The SNI list for matching the SSL certificate.

Responses

Request samples

Payload

Content type

application/json

{"type": "server",
"sni": "test.com",
"cert": "<content of server.crt>",
"key": "<content of server.key>"
}

Response samples

201

Content type

application/json

{"key": "/apisix/ssls/00000000000000000134",
"value": {"type": "server",
"cert": "<content of server.crt>",
"key": "<content of server.key>",
"id": "00000000000000000134",
"create_time": 1684374944,
"status": 1,
"snis": ["test.com"
],
"update_time": 1684374944
}
}

Create an SSL by ID

Create an SSL with a custom ID.

path Parameters

id

required

string

Specified SSL ID.

Request Body schema: application/json

One of

labels	object Key-value pairs to specify attributes.
desc	string <= 256 characters SSL description.
status	integer Default: 1 Enum: 1 0 SSL status. Set to `1` to enable and `0` to disable.
keys	Array of strings[ items [ 128 .. 65536 ] characters ] An array of private key content or reference to private key content.
key required	string [ 128 .. 65536 ] characters A private key content or reference to private key content.
sni required	string The SNI hostname for matching the SSL certificate.
ssl_protocols	Array of strings Items Enum: "TLSv1.1" "TLSv1.2" "TLSv1.3" An array of TLS protocol versions.
	string or integer Specified SSL ID.
	object Client certificate.
certs	Array of strings[ items [ 128 .. 65536 ] characters ] An array of certificate content or reference to the certificate content.
type	string Default: "server" Enum: "server" "client" APISIX acts as an SSL server or client.
cert required	string [ 128 .. 65536 ] characters Certificate content or reference to the certificate content.
snis	Array of strings non-empty The SNI list for matching the SSL certificate.

Responses

Request samples

Payload

Content type

application/json

{"type": "server",
"snis": ["test.com"
],
"cert": "<content of server.crt>",
"key": "<content of server.key>"
}

Response samples

201

Content type

application/json

{"key": "/apisix/ssls/1",
"value": {"type": "server",
"key": "<content of server.key>",
"snis": ["test.com"
],
"id": "1",
"create_time": 1684373523,
"status": 1,
"cert": "<content of server.crt>",
"update_time": 1684373523
}
}

Get SSL by ID

Get an SSL by ID.

path Parameters

id

required

string

Specified SSL ID.

Responses

Response samples

200

Content type

application/json

{"value": {"type": "server",
"snis": ["test.com"
],
"id": "1",
"create_time": 1684373523,
"status": 1,
"cert": "<content of server.crt>",
"update_time": 1684373523
},
"key": "/apisix/ssls/1",
"modifiedIndex": 133,
"createdIndex": 133
}

Delete SSL by ID

Delete an SSL by ID.

path Parameters

id

required

string

Specified SSL ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/ssls/00000000000000000134",
"deleted": "1"
}

Secret

Secret is used to set up integration with an external secret manager, so that APISIX can establish connections and fetch secrets from the secret manager dynamically at runtime.

See Secrets for more information.

Get All Secrets

Get all configured secrets.

Responses

Response samples

200

Content type

application/json

{"total": 1,
"list": [{"createdIndex": 179,
"key": "/apisix/secrets/vault/1",
"value": {"token": "343effad",
"id": "vault/1",
"uri": "https://localhost/vault",
"prefix": "/apisix/kv",
"update_time": 1684395392,
"create_time": 1684395392
},
"modifiedIndex": 179
}
]
}

Get Secrets by ID

Get a secret by ID.

path Parameters

secretmanager required	string Enum: "vault" "aws" "gcp" Secret manager.
id required	string The specified secrets ID.

Responses

Response samples

200

Content type

application/json

{"createdIndex": 179,
"key": "/apisix/secrets/vault/1",
"value": {"token": "343effad",
"id": "vault/1",
"uri": "https://localhost/vault",
"prefix": "/apisix/kv",
"update_time": 1684395392,
"create_time": 1684395392
},
"modifiedIndex": 179
}

Create a Secret

Create a secret with a custom ID to obtain secret from secret manager.

path Parameters

secretmanager required	string Enum: "vault" "aws" "gcp" Secret manager.
id required	string The specified secret ID.

Request Body schema: application/json

One of

uri required	string Address of the Vault server.
prefix required	string Path prefix of the secret engine that Vault should route to.
token required	string Token used for APISIX to authenticate to Vault.
namespace	string Used to set the namespace of HashiCorp Vault Enterprise and HCP Vault.

Responses

Request samples

Payload

Content type

application/json

{"uri": "https://localhost/vault",
"prefix": "/apisix/kv",
"token": "343effad",
"namespace": "apisix"
}

Response samples

201

Content type

application/json

{"value": {"prefix": "/apisix/kv",
"token": "343effad",
"uri": "https://localhost/vault",
"namespace": "apisix",
"id": "vault/1",
"update_time": 1684395392,
"create_time": 1684395392
},
"key": "/apisix/secrets/vault/1"
}

Update Secrets

Update a secret configuration.

path Parameters

secretmanager required	string Enum: "vault" "aws" "gcp" Secret manager.
id required	string The specified secret ID.

Request Body schema: application/json

uri required	string Endpoint URI of the secret manager service.
prefix required	string Path prefix for the secret engine or storage location.
token required	string Authentication token or credential for accessing the secret manager.

Responses

Request samples

Payload

Content type

application/json

{"token": "apisix"
}

Response samples

200

Content type

application/json

{"value": {"token": "apisix",
"id": "vault/1",
"uri": "https://localhost/vault",
"prefix": "/apisix/kv",
"update_time": 1684396605,
"create_time": 1684395392
},
"key": "/apisix/secrets/vault/1"
}

Delete Secret by ID

Delete a secret by ID.

path Parameters

secretmanager required	string Enum: "vault" "aws" "gcp" Secret manager.
id required	string The specified secret ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"deleted": "1",
"key": "/apisix/secrets/vault/1"
}

Proto

Proto is used to store protocol buffer (protobuf) definitions which define the service interface and message types used in communication with upstream gRPC services.

See Protos for more information.

Create Proto by ID

Create a proto with a custom ID.

path Parameters

id

required

string

Specified proto ID.

Request Body schema: application/json

content required	string Protobuf schema content in text format.
name	string [ 1 .. 100 ] characters Name of the proto configuration.
desc	string <= 256 characters Description of the proto configuration.
label	object Key-value pairs of custom labels.

Responses

Request samples

Payload

Content type

application/json

"{\n    \"content\": \"syntax = \\\"proto3\\\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }\"\n}"

Response samples

201

Content type

application/json

{"key": "/apisix/protos/1",
"value": {"id": "1",
"create_time": 1684752213,
"update_time": 1684752213,
"content": "syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }"
}
}

Get Proto by ID

Get a proto configuration by ID.

path Parameters

id

required

string

Specified proto ID.

Responses

Response samples

200

Content type

application/json

{"value": {"id": "1",
"content": "syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }",
"update_time": 1684752213,
"create_time": 1684752213
},
"key": "/apisix/protos/1",
"modifiedIndex": 292,
"createdIndex": 292
}

Delete Proto by ID

Delete a proto by ID.

path Parameters

id

required

string

Specified proto ID.

query Parameters

force

string

Example: force=true

Delete resource by force even if the resource is in use.

Responses

Response samples

200

Content type

application/json

{"key": "/apisix/protos/1",
"deleted": "1"
}

Get All Protos

Get all configured protos.

query Parameters

name	string Name to query protos by.
label	string Label to query protos by.

Responses

Response samples

200

Content type

application/json

{"list": [{"value": {"id": "1",
"content": "syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }",
"update_time": 1684752213,
"create_time": 1684752213
},
"key": "/apisix/protos/1",
"modifiedIndex": 292,
"createdIndex": 292
}
],
"total": 1
}

Create Proto

Create a proto with an ID generated.

Request Body schema: application/json

content required	string Protobuf schema content in text format.
name	string [ 1 .. 100 ] characters Name of the proto configuration.
desc	string <= 256 characters Description of the proto configuration.
label	object Key-value pairs of custom labels.

Responses

Request samples

Payload

Content type

application/json

"{\n    \"content\": \"syntax = \\\"proto3\\\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }\"\n}"

Response samples

201

Content type

application/json

{"key": "/apisix/protos/00000000000000000293",
"value": {"create_time": 1684752743,
"update_time": 1684752743,
"content": "syntax = \"proto3\";\n    package helloworld;\n    service Greeter {\n        rpc GetErrResp (HelloRequest) returns (HelloReply) {}\n    }\n    message HelloRequest {\n        string name = 1;\n        repeated string items = 2;\n    }\n    message HelloReply {\n        string message = 1;\n        repeated string items = 2;\n    }\n    message ErrorDetail {\n        int64 code = 1;\n        string message = 2;\n        string type = 3;\n    }",
"id": "00000000000000000293"
}
}

Schema Validation

Validate if the schema of a configuration is correct without sending a request to the Admin API for resource creation. This API can be used with all Admin API resources.

Validate Configuration Schema

Validate configuration schema without resource creation.

path Parameters

resource

required

string

Enum: "routes" "services" "upstreams" "consumers" "consumer_groups" "ssls" "gloabl_rules" "plugins" "plugin_metadata" "plugin_configs" "stream_routes" "secrets" "protos"

Example: routes

Type of resource.

Request Body schema: application/json

any

Responses

Request samples

Payload

Content type

application/json

{"uri": 1980,
"upstream": {"scheme": "https",
"type": "roundrobin",
"nodes": {"httpbin.org": 1
}
}
}