2021-02-26 21:40:08 +08:00
---
title: Control API
---
2020-12-18 15:05:09 +08:00
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
-->
2022-03-14 11:54:56 +08:00
In Apache APISIX, the control API is used to:
2021-01-03 11:26:40 +08:00
2022-03-14 11:54:56 +08:00
* Expose the internal state of APISIX.
* Control the behavior of a single, isolated APISIX data plane.
2020-12-18 15:05:09 +08:00
2022-03-14 11:54:56 +08:00
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`):
2020-12-18 15:05:09 +08:00
```yaml
apisix:
...
enable_control: true
control:
ip: "127.0.0.1"
port: 9090
```
2022-03-14 11:54:56 +08:00
To enable parameter matching in plugin's control API, add `router: 'radixtree_uri_with_parameter'` to the control section.
2021-12-29 10:15:45 +08:00
2022-03-14 11:54:56 +08:00
**Note**: Never configure the control API server to listen to public traffic.
2020-12-18 15:05:09 +08:00
2022-03-14 11:54:56 +08:00
## Control API Added via Plugins
2020-12-18 15:05:09 +08:00
2022-03-14 11:54:56 +08:00
[Plugins ](./architecture-design/plugin.md ) can be enabled to add its control API.
2020-12-18 15:05:09 +08:00
2022-03-14 11:54:56 +08:00
Some Plugins have their own control APIs. See the documentation of the specific Plugin to learn more.
2020-12-18 15:05:09 +08:00
2022-03-14 11:54:56 +08:00
## Plugin Independent Control API
The supported APIs are listed below.
2020-12-18 15:05:09 +08:00
### GET /v1/schema
2022-03-14 11:54:56 +08:00
Introduced in [v2.2 ](https://github.com/apache/apisix/releases/tag/2.2 ).
2020-12-18 15:05:09 +08:00
2022-03-14 11:54:56 +08:00
Returns the JSON schema used by the APISIX instance:
2021-01-03 11:26:40 +08:00
2020-12-23 16:40:19 +08:00
```json
{
"main": {
"route": {
"properties": {...}
},
"upstream": {
"properties": {...}
},
...
},
"plugins": {
"example-plugin": {
"consumer_schema": {...},
"metadata_schema": {...},
"schema": {...},
"type": ...,
"priority": 0,
"version": 0.1
},
...
2021-09-02 09:50:35 +08:00
},
"stream-plugins": {
"mqtt-proxy": {
...
},
...
2020-12-23 16:40:19 +08:00
}
}
```
2022-03-14 11:54:56 +08:00
**Note**: Only the enabled `plugins` are returned and they may lack fields like `consumer_schema` or `type` depending on how they were defined.
2021-01-20 18:06:03 +08:00
### GET /v1/healthcheck
2022-03-14 11:54:56 +08:00
Introduced in [v2.3 ](https://github.com/apache/apisix/releases/tag/2.3 ).
2021-01-20 18:06:03 +08:00
2022-03-14 11:54:56 +08:00
Returns a [health check ](health-check.md ) of the APISIX instance.
2021-01-20 18:06:03 +08:00
```json
[
{
"healthy_nodes": [
{
"host": "127.0.0.1",
"port": 1980,
2021-03-10 14:56:26 +08:00
"priority": 0,
2021-01-20 18:06:03 +08:00
"weight": 1
}
],
"name": "upstream#/upstreams/1",
"nodes": [
{
"host": "127.0.0.1",
"port": 1980,
2021-03-10 14:56:26 +08:00
"priority": 0,
2021-01-20 18:06:03 +08:00
"weight": 1
},
{
"host": "127.0.0.2",
"port": 1988,
2021-03-10 14:56:26 +08:00
"priority": 0,
2021-01-20 18:06:03 +08:00
"weight": 1
}
],
"src_id": "1",
"src_type": "upstreams"
},
{
"healthy_nodes": [
{
"host": "127.0.0.1",
"port": 1980,
2021-03-10 14:56:26 +08:00
"priority": 0,
2021-01-20 18:06:03 +08:00
"weight": 1
}
],
"name": "upstream#/routes/1",
"nodes": [
{
"host": "127.0.0.1",
"port": 1980,
2021-03-10 14:56:26 +08:00
"priority": 0,
2021-01-20 18:06:03 +08:00
"weight": 1
},
{
"host": "127.0.0.1",
"port": 1988,
2021-03-10 14:56:26 +08:00
"priority": 0,
2021-01-20 18:06:03 +08:00
"weight": 1
}
],
"src_id": "1",
"src_type": "routes"
}
]
```
2022-03-14 11:54:56 +08:00
Each of the returned objects contain the following fields:
2021-01-20 18:06:03 +08:00
2022-03-14 11:54:56 +08:00
* 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.
2021-01-20 18:06:03 +08:00
2022-03-14 11:54:56 +08:00
You can also use `/v1/healthcheck/$src_type/$src_id` to get the health status of specific nodes.
2021-01-20 18:06:03 +08:00
For example, `GET /v1/healthcheck/upstreams/1` returns:
```json
{
"healthy_nodes": [
{
"host": "127.0.0.1",
"port": 1980,
2021-03-10 14:56:26 +08:00
"priority": 0,
2021-01-20 18:06:03 +08:00
"weight": 1
}
],
"name": "upstream#/upstreams/1",
"nodes": [
{
"host": "127.0.0.1",
"port": 1980,
2021-03-10 14:56:26 +08:00
"priority": 0,
2021-01-20 18:06:03 +08:00
"weight": 1
},
{
"host": "127.0.0.2",
"port": 1988,
2021-03-10 14:56:26 +08:00
"priority": 0,
2021-01-20 18:06:03 +08:00
"weight": 1
}
],
"src_id": "1",
"src_type": "upstreams"
}
```
2021-06-24 09:45:00 +08:00
### POST /v1/gc
2022-03-14 11:54:56 +08:00
Introduced in [v2.8 ](https://github.com/apache/apisix/releases/tag/2.8 ).
Triggers a full garbage collection in the HTTP subsystem.
2021-06-24 09:45:00 +08:00
2022-03-14 11:54:56 +08:00
**Note**: When stream proxy is enabled, APISIX runs another Lua VM for the stream subsystem. Full garbage collection is not triggered in this VM.
2021-09-10 13:53:46 +08:00
2022-03-14 11:54:56 +08:00
### GET /v1/routes
2021-09-10 13:53:46 +08:00
2022-03-14 11:54:56 +08:00
Introduced in [v3.0 ](https://github.com/apache/apisix/releases/tag/3.0 ).
2021-09-10 13:53:46 +08:00
2022-03-14 11:54:56 +08:00
Returns all configured [Routes ](./architecture-design/route.md ):
2021-09-10 13:53:46 +08:00
```json
[
{
"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"
}
]
```
2022-03-14 11:54:56 +08:00
### GET /v1/route/{route_id}
2021-09-10 13:53:46 +08:00
2022-03-14 11:54:56 +08:00
Introduced in [v3.0 ](https://github.com/apache/apisix/releases/tag/3.0 ).
2021-09-10 13:53:46 +08:00
2022-03-14 11:54:56 +08:00
Returns the Route with the specified `route_id` :
2021-09-10 13:53:46 +08:00
```json
{
"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"
}
```
2021-10-19 12:57:41 +08:00
2022-03-14 11:54:56 +08:00
### GET /v1/services
2021-10-20 08:55:01 +08:00
2022-03-14 11:54:56 +08:00
Introduced in [v2.11 ](https://github.com/apache/apisix/releases/tag/2.11 ).
2021-10-20 08:55:01 +08:00
2022-03-14 11:54:56 +08:00
Returns all the Services:
2021-10-20 08:55:01 +08:00
```json
[
{
"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": [
{
2021-11-26 11:09:39 +08:00
"port": 1980,
2021-10-20 08:55:01 +08:00
"weight": 1,
2021-11-26 11:09:39 +08:00
"host": "127.0.0.1"
2021-10-20 08:55:01 +08:00
}
]
},
"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
}
}
]
```
2022-03-14 11:54:56 +08:00
### GET /v1/service/{service_id}
2021-10-20 08:55:01 +08:00
2022-03-14 11:54:56 +08:00
Introduced in [v2.11 ](https://github.com/apache/apisix/releases/tag/2.11 ).
2021-10-20 08:55:01 +08:00
2022-03-14 11:54:56 +08:00
Returns the Service with the specified `service_id` :
2021-10-20 08:55:01 +08:00
```json
{
"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": [
{
2021-11-26 11:09:39 +08:00
"port": 1980,
2021-10-20 08:55:01 +08:00
"weight": 1,
2021-11-26 11:09:39 +08:00
"host": "127.0.0.1"
2021-10-20 08:55:01 +08:00
}
]
},
"update_time": 1634554563
}
}
```
2022-03-14 11:54:56 +08:00
### GET /v1/upstreams
2021-10-19 12:57:41 +08:00
2022-03-14 11:54:56 +08:00
Introduced in [v2.11 ](https://github.com/apache/apisix/releases/tag/2.11 ).
2021-10-19 12:57:41 +08:00
2022-03-14 11:54:56 +08:00
Dumps all Upstreams:
2021-10-19 12:57:41 +08:00
```json
[
{
"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
}
]
```
2022-03-14 11:54:56 +08:00
### GET /v1/upstream/{upstream_id}
2021-10-19 12:57:41 +08:00
2022-03-14 11:54:56 +08:00
Introduced in [v2.11 ](https://github.com/apache/apisix/releases/tag/2.11 ).
2021-10-19 12:57:41 +08:00
2022-03-14 11:54:56 +08:00
Dumps the Upstream with the specified `upstream_id` :
2021-10-19 12:57:41 +08:00
```json
{
"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
}
```