Skip to main content
Version: 3.0.0-beta

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.

[
{
"healthy_nodes": [
{
"host": "127.0.0.1",
"port": 1980,
"priority": 0,
"weight": 1
}
],
"name": "upstream#/upstreams/1",
"nodes": [
{
"host": "127.0.0.1",
"port": 1980,
"priority": 0,
"weight": 1
},
{
"host": "127.0.0.2",
"port": 1988,
"priority": 0,
"weight": 1
}
],
"src_id": "1",
"src_type": "upstreams"
},
{
"healthy_nodes": [
{
"host": "127.0.0.1",
"port": 1980,
"priority": 0,
"weight": 1
}
],
"name": "upstream#/routes/1",
"nodes": [
{
"host": "127.0.0.1",
"port": 1980,
"priority": 0,
"weight": 1
},
{
"host": "127.0.0.1",
"port": 1988,
"priority": 0,
"weight": 1
}
],
"src_id": "1",
"src_type": "routes"
}
]

Each of the returned objects contain the following fields:

  • src_type: where the health checker is reporting from. Value is one of ["routes", "services", "upstreams"].
  • src_id: id of the object creating the health checker. For example, if an Upstream object with id 1 creates a health checker, the src_type is upstreams and the src_id is 1.
  • name: name of the health checker.
  • nodes: target nodes of the health checker.
  • healthy_nodes: healthy nodes discovered by the health checker.

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:

{
"healthy_nodes": [
{
"host": "127.0.0.1",
"port": 1980,
"priority": 0,
"weight": 1
}
],
"name": "upstream#/upstreams/1",
"nodes": [
{
"host": "127.0.0.1",
"port": 1980,
"priority": 0,
"weight": 1
},
{
"host": "127.0.0.2",
"port": 1988,
"priority": 0,
"weight": 1
}
],
"src_id": "1",
"src_type": "upstreams"
}
note

As APISIX uses multiple-process architecture, if the process never handles the request of a specific upstream, then the upstream's health check information will not appear on the process. This may result in the health check API can't get all data during testing.

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:

[
{
"update_count": 0,
"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:

{
"update_count": 0,
"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"
}