Skip to main content
Version: 3.8

Control API

In Apache APISIX, the control API is used to:

  • Expose the internal state of APISIX.
  • Control the behavior of a single, isolated APISIX data plane.

To change the default endpoint (127.0.0.1:9090) of the Control API server, change the ip and port in the control section in your configuration file (conf/config.yaml):

apisix:
...
enable_control: true
control:
ip: "127.0.0.1"
port: 9090

To enable parameter matching in plugin's control API, add router: 'radixtree_uri_with_parameter' to the control section.

Note: Never configure the control API server to listen to public traffic.

Control API Added via Plugins#

Plugins can be enabled to add its control API.

Some Plugins have their own control APIs. See the documentation of the specific Plugin to learn more.

Plugin Independent Control API#

The supported APIs are listed below.

GET /v1/schema#

Introduced in v2.2.

Returns the JSON schema used by the APISIX instance:

{
"main": {
"route": {
"properties": {...}
},
"upstream": {
"properties": {...}
},
...
},
"plugins": {
"example-plugin": {
"consumer_schema": {...},
"metadata_schema": {...},
"schema": {...},
"type": ...,
"priority": 0,
"version": 0.1
},
...
},
"stream-plugins": {
"mqtt-proxy": {
...
},
...
}
}

Note: Only the enabled plugins are returned and they may lack fields like consumer_schema or type depending on how they were defined.

GET /v1/healthcheck#

Introduced in v2.3.

Returns a health check of the APISIX instance.

[
{
"nodes": [
{
"ip": "52.86.68.46",
"counter": {
"http_failure": 0,
"success": 0,
"timeout_failure": 0,
"tcp_failure": 0
},
"port": 80,
"status": "healthy"
},
{
"ip": "100.24.156.8",
"counter": {
"http_failure": 5,
"success": 0,
"timeout_failure": 0,
"tcp_failure": 0
},
"port": 80,
"status": "unhealthy"
}
],
"name": "/apisix/routes/1",
"type": "http"
}
]

Each of the returned objects contain the following fields:

  • name: resource id, where the health checker is reporting from.
  • type: health check type: ["http", "https", "tcp"].
  • nodes: target nodes of the health checker.
  • nodes[i].ip: ip address.
  • nodes[i].port: port number.
  • nodes[i].status: health check result: ["healthy", "unhealthy", "mostly_healthy", "mostly_unhealthy"].
  • nodes[i].counter.success: success health check count.
  • nodes[i].counter.http_failure: http failures count.
  • nodes[i].counter.tcp_failure: tcp connect/read/write failures count.
  • nodes[i].counter.timeout_failure: timeout count.

You can also use /v1/healthcheck/$src_type/$src_id to get the health status of specific nodes.

For example, GET /v1/healthcheck/upstreams/1 returns:

{
"nodes": [
{
"ip": "52.86.68.46",
"counter": {
"http_failure": 0,
"success": 2,
"timeout_failure": 0,
"tcp_failure": 0
},
"port": 80,
"status": "healthy"
},
{
"ip": "100.24.156.8",
"counter": {
"http_failure": 5,
"success": 0,
"timeout_failure": 0,
"tcp_failure": 0
},
"port": 80,
"status": "unhealthy"
}
],
"type": "http"
"name": "/apisix/routes/1"
}

note

Only when one upstream is satisfied by the conditions below, its status is shown in the result list:

  • The upstream is configured with a health checker
  • The upstream has served requests in any worker process

If you use browser to access the control API URL, then you will get the HTML output:

POST /v1/gc#

Introduced in v2.8.

Triggers a full garbage collection in the HTTP subsystem.

Note: When stream proxy is enabled, APISIX runs another Lua VM for the stream subsystem. Full garbage collection is not triggered in this VM.

GET /v1/routes#

Introduced in v2.10.0.

Returns all configured Routes:

[
{
"value": {
"priority": 0,
"uris": [
"/hello"
],
"id": "1",
"upstream": {
"scheme": "http",
"pass_host": "pass",
"nodes": [
{
"port": 1980,
"host": "127.0.0.1",
"weight": 1
}
],
"type": "roundrobin",
"hash_on": "vars"
},
"status": 1
},
"clean_handlers": {},
"has_domain": false,
"orig_modifiedIndex": 1631193445,
"modifiedIndex": 1631193445,
"key": "/routes/1"
}
]

GET /v1/route/{route_id}#

Introduced in v2.10.0.

Returns the Route with the specified route_id:

{
"value": {
"priority": 0,
"uris": [
"/hello"
],
"id": "1",
"upstream": {
"scheme": "http",
"pass_host": "pass",
"nodes": [
{
"port": 1980,
"host": "127.0.0.1",
"weight": 1
}
],
"type": "roundrobin",
"hash_on": "vars"
},
"status": 1
},
"clean_handlers": {},
"has_domain": false,
"orig_modifiedIndex": 1631193445,
"modifiedIndex": 1631193445,
"key": "/routes/1"
}

GET /v1/services#

Introduced in v2.11.0.

Returns all the Services:

[
{
"has_domain": false,
"clean_handlers": {},
"modifiedIndex": 671,
"key": "/apisix/services/200",
"createdIndex": 671,
"value": {
"upstream": {
"scheme": "http",
"hash_on": "vars",
"pass_host": "pass",
"type": "roundrobin",
"nodes": [
{
"port": 1980,
"weight": 1,
"host": "127.0.0.1"
}
]
},
"create_time": 1634552648,
"id": "200",
"plugins": {
"limit-count": {
"key": "remote_addr",
"time_window": 60,
"redis_timeout": 1000,
"allow_degradation": false,
"show_limit_quota_header": true,
"policy": "local",
"count": 2,
"rejected_code": 503
}
},
"update_time": 1634552648
}
}
]

GET /v1/service/{service_id}#

Introduced in v2.11.0.

Returns the Service with the specified service_id:

{
"has_domain": false,
"clean_handlers": {},
"modifiedIndex": 728,
"key": "/apisix/services/5",
"createdIndex": 728,
"value": {
"create_time": 1634554563,
"id": "5",
"upstream": {
"scheme": "http",
"hash_on": "vars",
"pass_host": "pass",
"type": "roundrobin",
"nodes": [
{
"port": 1980,
"weight": 1,
"host": "127.0.0.1"
}
]
},
"update_time": 1634554563
}
}

GET /v1/upstreams#

Introduced in v2.11.0.

Dumps all Upstreams:

[
{
"value":{
"scheme":"http",
"pass_host":"pass",
"nodes":[
{
"host":"127.0.0.1",
"port":80,
"weight":1
},
{
"host":"foo.com",
"port":80,
"weight":2
}
],
"hash_on":"vars",
"update_time":1634543819,
"key":"remote_addr",
"create_time":1634539759,
"id":"1",
"type":"chash"
},
"has_domain":true,
"key":"\/apisix\/upstreams\/1",
"clean_handlers":{
},
"createdIndex":938,
"modifiedIndex":1225
}
]

GET /v1/upstream/{upstream_id}#

Introduced in v2.11.0.

Dumps the Upstream with the specified upstream_id:

{
"value":{
"scheme":"http",
"pass_host":"pass",
"nodes":[
{
"host":"127.0.0.1",
"port":80,
"weight":1
},
{
"host":"foo.com",
"port":80,
"weight":2
}
],
"hash_on":"vars",
"update_time":1634543819,
"key":"remote_addr",
"create_time":1634539759,
"id":"1",
"type":"chash"
},
"has_domain":true,
"key":"\/apisix\/upstreams\/1",
"clean_handlers":{
},
"createdIndex":938,
"modifiedIndex":1225
}

GET /v1/plugin_metadatas#

Introduced in v3.0.0.

Dumps all plugin_metadatas:

[
{
"log_format": {
"upstream_response_time": "$upstream_response_time"
},
"id": "file-logger"
},
{
"ikey": 1,
"skey": "val",
"id": "example-plugin"
}
]

GET /v1/plugin_metadata/{plugin_name}#

Introduced in v3.0.0.

Dumps the metadata with the specified plugin_name:

{
"log_format": {
"upstream_response_time": "$upstream_response_time"
},
"id": "file-logger"
}