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.         "healthy_nodes": [
  4.             {
  5.                 "host": "127.0.0.1",
  6.                 "port": 1980,
  7.                 "priority": 0,
  8.                 "weight": 1
  9.             }
  10.         ],
  11.         "name": "upstream#/upstreams/1",
  12.         "nodes": [
  13.             {
  14.                 "host": "127.0.0.1",
  15.                 "port": 1980,
  16.                 "priority": 0,
  17.                 "weight": 1
  18.             },
  19.             {
  20.                 "host": "127.0.0.2",
  21.                 "port": 1988,
  22.                 "priority": 0,
  23.                 "weight": 1
  24.             }
  25.         ],
  26.         "src_id": "1",
  27.         "src_type": "upstreams"
  28.     },
  29.     {
  30.         "healthy_nodes": [
  31.             {
  32.                 "host": "127.0.0.1",
  33.                 "port": 1980,
  34.                 "priority": 0,
  35.                 "weight": 1
  36.             }
  37.         ],
  38.         "name": "upstream#/routes/1",
  39.         "nodes": [
  40.             {
  41.                 "host": "127.0.0.1",
  42.                 "port": 1980,
  43.                 "priority": 0,
  44.                 "weight": 1
  45.             },
  46.             {
  47.                 "host": "127.0.0.1",
  48.                 "port": 1988,
  49.                 "priority": 0,
  50.                 "weight": 1
  51.             }
  52.         ],
  53.         "src_id": "1",
  54.         "src_type": "routes"
  55.     }
  56. ]

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:

  1. {
  2.     "healthy_nodes": [
  3.         {
  4.             "host": "127.0.0.1",
  5.             "port": 1980,
  6.             "priority": 0,
  7.             "weight": 1
  8.         }
  9.     ],
  10.     "name": "upstream#/upstreams/1",
  11.     "nodes": [
  12.         {
  13.             "host": "127.0.0.1",
  14.             "port": 1980,
  15.             "priority": 0,
  16.             "weight": 1
  17.         },
  18.         {
  19.             "host": "127.0.0.2",
  20.             "port": 1988,
  21.             "priority": 0,
  22.             "weight": 1
  23.         }
  24.     ],
  25.     "src_id": "1",
  26.     "src_type": "upstreams"
  27. }
Control API - 图1note

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:

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

GET /v1/route/{route_id}

Introduced in v2.10.0.

Returns the Route with the specified route_id:

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

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. }