Control API

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

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

    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.

    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.

    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.

    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.                 "port": 1988,
    48.                 "priority": 0,
    49.                 "weight": 1
    50.             }
    51.         ],
    52.         "src_id": "1",
    53.         "src_type": "routes"
    55. ]

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

    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.

    Introduced in .

    Returns all configured Routes:

    GET /v1/route/{route_id}

    Introduced in v2.10.0.

    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.       "create_time": 1634552648,
    22.       "id": "200",
    23.       "plugins": {
    25.           "key": "remote_addr",
    26.           "time_window": 60,
    27.           "redis_timeout": 1000,
    28.           "allow_degradation": false,
    29.           "show_limit_quota_header": true,
    30.           "policy": "local",
    31.           "count": 2,
    32.           "rejected_code": 503
    33.         }
    34.       },
    35.       "update_time": 1634552648
    36.     }
    37.   }
    38. ]

    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:

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

    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}

    Dumps the metadata with the specified plugin_name:

    1. {
    2.     "log_format": {
    3.         "upstream_response_time": "$upstream_response_time"
    4.     },