Skip to main content
Version: 2.15

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
}