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):

  1. apisix:
  2.   ...
  3.   enable_control: true
  4.   control:
  5.     ip: "127.0.0.1"
  6.     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:

  1. {
  2.     "main": {
  3.         "route": {
  4.             "properties": {...}
  5.         },
  6.         "upstream": {
  7.             "properties": {...}
  8.         },
  9.         ...
  10.     },
  11.     "plugins": {
  12.         "example-plugin": {
  13.             "consumer_schema": {...},
  14.             "metadata_schema": {...},
  15.             "schema": {...},
  16.             "type": ...,
  17.             "priority": 0,
  18.             "version": 0.1
  19.         },
  20.         ...
  21.     },
  22.     "stream-plugins": {
  23.         "mqtt-proxy": {
  24.             ...
  25.         },
  26.         ...
  27.     }
  28. }

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.

  1. [
  2.   {
  3.     "nodes": [
  4.       {
  5.         "ip": "52.86.68.46",
  6.         "counter": {
  7.           "http_failure": 0,
  8.           "success": 0,
  9.           "timeout_failure": 0,
  10.           "tcp_failure": 0
  11.         },
  12.         "port": 80,
  13.         "status": "healthy"
  14.       },
  15.       {
  16.         "ip": "100.24.156.8",
  17.         "counter": {
  18.           "http_failure": 5,
  19.           "success": 0,
  20.           "timeout_failure": 0,
  21.           "tcp_failure": 0
  22.         },
  23.         "port": 80,
  24.         "status": "unhealthy"
  25.       }
  26.     ],
  27.     "name": "/apisix/routes/1",
  28.     "type": "http"
  29.   }
  30. ]

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:

  1. {
  2.   "nodes": [
  3.     {
  4.       "ip": "52.86.68.46",
  5.       "counter": {
  6.         "http_failure": 0,
  7.         "success": 2,
  8.         "timeout_failure": 0,
  9.         "tcp_failure": 0
  10.       },
  11.       "port": 80,
  12.       "status": "healthy"
  13.     },
  14.     {
  15.       "ip": "100.24.156.8",
  16.       "counter": {
  17.         "http_failure": 5,
  18.         "success": 0,
  19.         "timeout_failure": 0,
  20.         "tcp_failure": 0
  21.       },
  22.       "port": 80,
  23.       "status": "unhealthy"
  24.     }
  25.   ],
  26.   "type": "http"
  27.   "name": "/apisix/routes/1"
  28. }
Control API - 图1note

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:

Health Check Status Page

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:

  1. [
  2.   {
  3.     "value": {
  4.       "priority": 0,
  5.       "uris": [
  6.         "/hello"
  7.       ],
  8.       "id": "1",
  9.       "upstream": {
  10.         "scheme": "http",
  11.         "pass_host": "pass",
  12.         "nodes": [
  13.           {
  14.             "port": 1980,
  15.             "host": "127.0.0.1",
  16.             "weight": 1
  17.           }
  18.         ],
  19.         "type": "roundrobin",
  20.         "hash_on": "vars"
  21.       },
  22.       "status": 1
  23.     },
  24.     "clean_handlers": {},
  25.     "has_domain": false,
  26.     "orig_modifiedIndex": 1631193445,
  27.     "modifiedIndex": 1631193445,
  28.     "key": "/routes/1"
  29.   }
  30. ]

GET /v1/route/{route_id}

Introduced in v2.10.0.

Returns the Route with the specified route_id:

  1. {
  2.   "value": {
  3.     "priority": 0,
  4.     "uris": [
  5.       "/hello"
  6.     ],
  7.     "id": "1",
  8.     "upstream": {
  9.       "scheme": "http",
  10.       "pass_host": "pass",
  11.       "nodes": [
  12.         {
  13.           "port": 1980,
  14.           "host": "127.0.0.1",
  15.           "weight": 1
  16.         }
  17.       ],
  18.       "type": "roundrobin",
  19.       "hash_on": "vars"
  20.     },
  21.     "status": 1
  22.   },
  23.   "clean_handlers": {},
  24.   "has_domain": false,
  25.   "orig_modifiedIndex": 1631193445,
  26.   "modifiedIndex": 1631193445,
  27.   "key": "/routes/1"
  28. }

GET /v1/services

Introduced in v2.11.0.

Returns all the Services:

  1. [
  2.   {
  3.     "has_domain": false,
  4.     "clean_handlers": {},
  5.     "modifiedIndex": 671,
  6.     "key": "/apisix/services/200",
  7.     "createdIndex": 671,
  8.     "value": {
  9.       "upstream": {
  10.           "scheme": "http",
  11.           "hash_on": "vars",
  12.           "pass_host": "pass",
  13.           "type": "roundrobin",
  14.           "nodes": [
  15.             {
  16.               "port": 1980,
  17.               "weight": 1,
  18.               "host": "127.0.0.1"
  19.             }
  20.           ]
  21.       },
  22.       "create_time": 1634552648,
  23.       "id": "200",
  24.       "plugins": {
  25.         "limit-count": {
  26.           "key": "remote_addr",
  27.           "time_window": 60,
  28.           "redis_timeout": 1000,
  29.           "allow_degradation": false,
  30.           "show_limit_quota_header": true,
  31.           "policy": "local",
  32.           "count": 2,
  33.           "rejected_code": 503
  34.         }
  35.       },
  36.       "update_time": 1634552648
  37.     }
  38.   }
  39. ]

GET /v1/service/{service_id}

Introduced in v2.11.0.

Returns the Service with the specified service_id:

  1. {
  2.   "has_domain": false,
  3.   "clean_handlers": {},
  4.   "modifiedIndex": 728,
  5.   "key": "/apisix/services/5",
  6.   "createdIndex": 728,
  7.   "value": {
  8.     "create_time": 1634554563,
  9.     "id": "5",
  10.     "upstream": {
  11.       "scheme": "http",
  12.       "hash_on": "vars",
  13.       "pass_host": "pass",
  14.       "type": "roundrobin",
  15.       "nodes": [
  16.         {
  17.           "port": 1980,
  18.           "weight": 1,
  19.           "host": "127.0.0.1"
  20.         }
  21.       ]
  22.     },
  23.     "update_time": 1634554563
  24.   }
  25. }

GET /v1/upstreams

Introduced in v2.11.0.

Dumps all Upstreams:

  1. [
  2.    {
  3.       "value":{
  4.          "scheme":"http",
  5.          "pass_host":"pass",
  6.          "nodes":[
  7.             {
  8.                "host":"127.0.0.1",
  9.                "port":80,
  10.                "weight":1
  11.             },
  12.             {
  13.                "host":"foo.com",
  14.                "port":80,
  15.                "weight":2
  16.             }
  17.          ],
  18.          "hash_on":"vars",
  19.          "update_time":1634543819,
  20.          "key":"remote_addr",
  21.          "create_time":1634539759,
  22.          "id":"1",
  23.          "type":"chash"
  24.       },
  25.       "has_domain":true,
  26.       "key":"\/apisix\/upstreams\/1",
  27.       "clean_handlers":{
  28.       },
  29.       "createdIndex":938,
  30.       "modifiedIndex":1225
  31.    }
  32. ]

GET /v1/upstream/{upstream_id}

Introduced in v2.11.0.

Dumps the Upstream with the specified upstream_id:

  1. {
  2.    "value":{
  3.       "scheme":"http",
  4.       "pass_host":"pass",
  5.       "nodes":[
  6.          {
  7.             "host":"127.0.0.1",
  8.             "port":80,
  9.             "weight":1
  10.          },
  11.          {
  12.             "host":"foo.com",
  13.             "port":80,
  14.             "weight":2
  15.          }
  16.       ],
  17.       "hash_on":"vars",
  18.       "update_time":1634543819,
  19.       "key":"remote_addr",
  20.       "create_time":1634539759,
  21.       "id":"1",
  22.       "type":"chash"
  23.    },
  24.    "has_domain":true,
  25.    "key":"\/apisix\/upstreams\/1",
  26.    "clean_handlers":{
  27.    },
  28.    "createdIndex":938,
  29.    "modifiedIndex":1225
  30. }

GET /v1/plugin_metadatas

Introduced in v3.0.0.

Dumps all plugin_metadatas:

  1. [
  2.     {
  3.         "log_format": {
  4.             "upstream_response_time": "$upstream_response_time"
  5.         },
  6.         "id": "file-logger"
  7.     },
  8.     {
  9.         "ikey": 1,
  10.         "skey": "val",
  11.         "id": "example-plugin"
  12.     }
  13. ]

GET /v1/plugin_metadata/{plugin_name}

Introduced in v3.0.0.

Dumps the metadata with the specified plugin_name:

  1. {
  2.     "log_format": {
  3.         "upstream_response_time": "$upstream_response_time"
  4.     },
  5.     "id": "file-logger"
  6. }

PUT /v1/plugins/reload

Introduced in v3.9.0

Triggers a hot reload of the plugins.

  1. curl "http://127.0.0.1:9090/v1/plugins/reload" -X PUT