APISIX Control API (3.17.0)

Download OpenAPI specification:Download

APISIX Control API is used to get the internal state of APISIX. In addition to the endpoints listed below, certain plugins, such as server-info, can add additional endpoints to control API.

Schema

The schema defines the available parameters as well as their data types, properties, default values, valid values, and so on.

Get JSON Schema

Get JSON schema that is used by the APISIX instance.

Responses

Response samples

200
400

Content type

application/json

{"1": {"summary": "Successful Example",
"value": {"value": {"main": {"route": {"properties": { }
},
"upstream": {"properties": { }
}
},
"plugins": {"example-plugin": {"consumer_schema": { },
"metadata_schema": { },
"schema": { },
"type": "object",
"priority": 0,
"version": 0.1
}
},
"stream-plugins": {"mqtt-proxy": { }
}
}
}
}
}

Health Check

Health checking is a mechanism that determines whether upstream services are healthy or unhealthy based on their responsiveness.

Get Health Check Information

Get health check information of the APISIX instance. You need to initiate a request to the route to generate Control API health check information.

Responses

Response samples

200

Content type

application/json

Example

Successful Example

{"nodes": [{"ip": "52.86.68.46",
"counter": {"http_failure": 0,
"success": 0,
"timeout_failure": 0,
"tcp_failure": 0
},
"port": 80,
"status": "healthy"
},
{"ip": "100.24.156.8",
"counter": {"http_failure": 5,
"success": 0,
"timeout_failure": 0,
"tcp_failure": 0
},
"port": 80,
"status": "unhealthy"
}
],
"name": "/apisix/routes/1",
"type": "http"
}

Get Health Status By Type and ID

Get health status of a specified resource.

path Parameters

src_type required	string Enum: "routes" "services" "upstreams" "stream_routes" The specified resource type.
src_id required	string The specified node ID.

Responses

Response samples

200
400
404

Content type

application/json

{"nodes": [{"ip": "52.86.68.46",
"counter": {"http_failure": 0,
"success": 2,
"timeout_failure": 0,
"tcp_failure": 0
},
"port": 80,
"status": "healthy"
},
{"ip": "100.24.156.8",
"counter": {"http_failure": 5,
"success": 0,
"timeout_failure": 0,
"tcp_failure": 0
},
"port": 80,
"status": "unhealthy"
}
],
"type": "http",
"name": "/apisix/routes/1"
}

Garbage Collection

Garbage collection is a form of automatic memory management. The garbage collector attempts to reclaim memory which was allocated by the program, but is no longer referenced.

Trigger Garbage Collection

Trigger a full garbage collection (GC) in the HTTP subsystem. Note that a request to this endpoint would not trigger a garbage collection in the stream subsystem because the subsystems are run in the separate Lua VM.

Responses

Response samples

200

Content type

application/json

{ }

Route

A route defines a path to one or more upstream services.

See Routes for more information.

Get All Routes

Get all configured routes.

Responses

Response samples

200

Content type

application/json

{"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
}

Get Route by ID

Get a route by ID.

path Parameters

id

required

string

The specified route ID.

Responses

Response samples

200
404

Content type

application/json

{"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
}

Upstream

An upstream is a logical abstraction of one or more upstream addresses.

See Upstreams for more information.

Get All Upstreams

Get all configured upstreams.

Responses

Response samples

200

Content type

application/json

{"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"
}

Get Upstream by ID

Get an upstream by ID.

path Parameters

id

required

string

The specified upstream ID.

Responses

Response samples

200
404

Content type

application/json

{"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"
}

Service

A service is a backend application providing a set of functionalities.

See Services for more information.

Get All Services

Get all configured services.

Responses

Response samples

200

Content type

application/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": [{"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 Service by ID

Get a service by ID.

path Parameters

id

required

string

The pecified service ID.

Responses

Response samples

200
404

Content type

application/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": [{"port": 1980,
"weight": 1,
"host": "127.0.0.1"
}
]
},
"update_time": 1634554563
}
}

Plugin Metadata

Plugin metadata is used to configure the common metadata field(s) of all plugin instances sharing the same plugin name.
See Plugin Metadata for more information.

Get All Plugin Metadata

Get all plugin metadata.

Responses

Response samples

200

Content type

application/json

[{"log_format": {"upstream_response_time": "$upstream_response_time"
},
"id": "file-logger"
},
{"ikey": 1,
"skey": "val",
"id": "example-plugin"
}
]

Get Plugin Metadata by Name

Get plugin metadata by the plugin name.

path Parameters

plugin_name

required

string

The specified plugin name.

Responses

Response samples

200
404

Content type

application/json

{"log_format": {"upstream_response_time": "$upstream_response_time"
},
"id": "file-logger"
}

Plugin

Plugins extend base functionalities of APISIX to meet user-specific requirements.

See Plugins for more information.

Reload All Plugins

Hot reload plugins for changes to the plugin list in configuration files or plugin source files to take effect.

Responses

Response samples

200

Content type

application/json

"done"

Service Discovery

Service discovery is a process used in microservice-based architectures for automatically detecting and registering dynamically assigned upstream addresses.

See Service Discovery for more information.

Get Memory Dump

Get service and configuration details.

Responses

Response samples

200
404

Content type

application/json

{"services": {"svc-a": [{"host": "192.168.42.145",
"weight": 1,
"port": 9081
},
{"host": "192.168.42.145",
"weight": 1,
"port": 9082
}
]
},
"config": {"dump": {"load_on_init": true,
"expire": 2592000,
"path": "logs/consul.dump"
},
"timeout": {"wait": 60,
"read": 2000,
"connect": 2000
},
"fetch_interval": 3,
"keepalive": true,
"weight": 1,
"servers": ["http://consul:8500"
],
"token": ""
}
}

Get Dump File

Get configured services details.

Responses

Response samples

200
404
503

Content type

application/json

{"last_update": 1703594980,
"services": {"svc-a": [{"host": "192.168.42.145",
"weight": 1,
"port": 9081
},
{"host": "192.168.42.145",
"weight": 1,
"port": 9082
}
]
},
"expire": 2592000
}