Knowing the basePath prefix is assumed. The basePath contains the API version, such as "/api/20190715". For example, if the endpoint is "/metadata" then the URL is similar to "https://localhost:8443/api/20190715/metadata". See Section 6.1, “A Simple MySQL Router REST API Guide” for related information.
Table 6.1 MySQL Router REST API Endpoints
| Endpoint | Description | Plugin | Method |
|---|---|---|---|
| /host_cache/config | Get host_cache configuration | host_cache | GET |
| /host_cache/status | Get host_cache status | host_cache | GET |
| /host_cache/entries | Get host_cache entries | host_cache | GET |
| /metadata | Get metadata instance names | rest_metadata_cache | GET |
| /metadata/{metadataName}/config | Get metadata configuration details | rest_metadata_cache | GET |
| /metadata/{metadataName}/status | Check metadata status | rest_metadata_cache | GET |
| /router/status | Check Router status | rest_router | GET |
| /routes | Get list of routes | rest_routing | GET |
| /routes/{routeName}/blockedHosts | Get list of blocked IPs | rest_routing | GET |
| /routes/{routeName}/config | Get route configuration details | rest_routing | GET |
| /routes/{routeName}/connections | Get route connections | rest_routing | GET |
| /routes/{routeName}/destinations | Get route destinations | rest_routing | GET |
| /routes/{routeName}/health | Check route health | rest_routing | GET |
| /routes/{routeName}/status | Check route status | rest_routing | GET |
| /connection_pool/{name}/config | Check connection_pool config | rest_connection_pool | GET |
| /connection_pool/{name}/status | Check connection_pool status | rest_connection_pool | GET |
| swagger.json | Get swagger file containing available paths and information | rest_api | GET |
Get host_cache configuration
Available Responses
- 200
-
Description: configuration of host_cache
Response Content-Type: application/json
Response Schema
- enabled
-
boolean
Whether the host cache is enabled
- maxEntries
-
integer
Maximum number of entries allowed in the LRU cache
- ttlSuccessSeconds
-
integer
Base TTL applied to successful DNS resolutions. Lookups returning at least one usable address.
- ttlNegativeSeconds
-
integer
Base TTL applied to deterministic negative outcomes, such as NXDOMAIN/NODATA/NOERROR-with-no-records.
- jitterRatio
-
integer
TTL jitter ratio in range [0.0 .. 0.5]
Example 200 response data:
{
"enabled": true,
"maxEntries": 250,
"ttlSuccessSeconds": 60,
"ttlNegativeSeconds": 10,
"jitterRatio": 0.2
}
Get host_cache usage and current cache state.
Available Responses
- 200
-
Description: Returns counters and high-level state about cache effectiveness and utilization.
Response Content-Type: application/json
Response Schema
- numberOfEntries
-
integer
Current number of entries stored in the LRU cache
- numberOfTemporaryEntries
-
integer
Current number of in-flight (temporary) entries, hostnames being resolved.
- cache
-
object
Effectiveness and maintenance counters:
hits: (integer) Number of cache hits, lookup served from non-expired LRU entry.misses: (integer) Number of cache misses, lookup required DNS resolution.inserts: (integer) Number of inserted final entries.evictions: (integer) Number of LRU evictions due to reaching maxEntries.expiredPurges: (integer) Number of entries purged because they expired.
Example 200 response data:
{
"numberOfEntries": 12,
"numberOfTemporaryEntries": 1,
"cache": {
"hits": 100,
"misses": 25,
"inserts": 20,
"evictions": 3,
"expiredPurges": 5
}
}
Get host_cache LRU entries and in-flight resolutions.
To keep the payload compact and stable,
entries and inProgress
are represented as JSON objects keyed by hostname (not
arrays). This also makes hostname lookup trivial for operators
and tools.
Available Responses
- 200
-
Description: Returns the current content of the LRU cache (final entries), and the in-flight container (temporary entries).
Response Content-Type: application/json
Response Schema
- entries
-
object
Hostname and entry information:
secondsRemainingTtl: (integer) Remaining TTL in seconds for the cached entry.cacheHits: (integer) Number of times this entry was returned as a cache hit.ttl: (integer) Initial effective TTL (in seconds) assigned to this cache entry at insertion time. That is, after applying ttlSuccessSeconds, ttlNegativeSeconds, and jitter.singleFlight: (integer) Number of concurrent consumers that waited on the same in-flight resolution that produced this entry. The waiter count observed for the single-flight DNS lookup at the time it completed.
- inProgress
-
object
Hostname and progress information:
ageMilliseconds: (integer) Time since the resolution started.consumers: (integer) Number of concurrent waiters for the in-flight. resolution.
Example 200 response data:
{
"entries": {
"myhostname1": {
"secondsRemainingTtl": 10,
"cacheHits": 1
}
},
"inProgress": {
"myhostname2": { "ageMilliseconds": 1200, "consumers": 1 },
"myhostname3": { "ageMilliseconds": 200, "consumers": 3 }
}
}
GET /metadata
Get list of the metadata cache instances
Available Responses
- 200
-
Description: List of metadata cache instances
Response Schema
- items
-
array
Contains 'name' fields; the name of the metadata instance
Example 200 response data:
{
"items": [
{
"name": "myCluster"
}
]
}
GET
/metadata/{metadataName}/config
Get configuration of the metadata cache of a cluster's replicaset
Available Responses
- 200
-
Description: Config of metadata cache
Response Schema
- clusterName
-
string
Optional, name of the replication group
- timeRefreshInMs
-
integer
TTL number
- groupReplicationId
-
string
Optional
- nodes
-
array
An array; items include the hostname (string) and port (integer) properties
- 404
Description: Cache not found
Path Parameters
- metadataName (required)
-
string
Name of cluster
Example 200 response data:
{
"clusterName": "myCluster",
"timeRefreshInMs": 500,
"groupReplicationId": "e57e9c11-abfe-11ea-b747-0800278566cb",
"nodes": [
{
"hostname": "127.0.0.1",
"port": 3310
},
{
"hostname": "127.0.0.1",
"port": 3320
},
{
"hostname": "127.0.0.1",
"port": 3330
}
]
}
GET
/metadata/{metadataName}/status
Get metadata cache status for a cluster's replicaset
Available Responses
- 200
-
Description: Status of the metadata cache
Response Schema
- lastRefreshHostname
-
string
- lastRefreshPort
-
integer
- timeLastRefreshFailed
-
string
- timeLastRefreshSucceeded
-
string
- refreshSucceeded
-
integer
- refreshFailed
-
integer
- 404
Description: Cache not found
Path Parameters
- metadataName (required)
-
string
Name of the cluster
Example 200 response data:
{
"refreshFailed": 0,
"refreshSucceeded": 798,
"timeLastRefreshSucceeded": "2020-06-11T21:17:37.270303Z",
"lastRefreshHostname": "127.0.0.1",
"lastRefreshPort": 3310
}
Get status of router
Available Responses
- 200
-
Description: Status of Router
Response Content-Type: application/json
Response Schema
- hostname
-
string
Name of the host the application is running on; it may be empty if a host is not configured
- processId
-
integer
Process ID of the application
- productEdition
-
string
Product edition, such as "MySQL Community - GPL"
- timeStarted
-
string
A date-time string that the application was started, such as "2020-06-11T22:08:30.978640Z"
- version
-
string
Version of the application, such as "8.0.22"
Example 200 response data:
{
"processId": 6435,
"productEdition": "MySQL Community - GPL",
"timeStarted": "2020-06-11T21:10:49.420619Z",
"version": "8.0.20",
"hostname": "boat"
}
GET /routes
Get list (names) of the routes supported by MySQL Router
Available Responses
- 200
-
Description: List of the supported routes
Response Schema
- items
-
array
A list of routes
Example 200 response data:
{
"items": [
{
"name": "myCluster_ro"
},
{
"name": "myCluster_rw"
},
{
"name": "myCluster_x_ro"
},
{
"name": "myCluster_x_rw"
}
]
}
GET
/routes/{routeName}/config
Get config of a route
Available Responses
- 200
-
Description: Config of a route
Response Schema
- bindAddress
-
string
Address the route is listening on
- bindPort
-
integer
TCP port the router is listening on
- clientConnectTimeoutInMs
-
integer
Connection timeout for incoming connections
- destinationConnectTimeoutInMs
-
integer
Connection timeout for outgoing connections
- maxActiveConnections
-
integer
Maximum number of active connections
- maxConnectErrors
-
integer
Maximum number of adjacent connection errors before the client gets blocked
- protocol
-
string
Protocol, either 'classic' or 'x'
- socket
-
string
Listening socket or named pipe
- routingStrategy
-
string
The routing strategy used; such as "round-robin", "round-robin-with-fallback", "first-available", or "next-available" as defined by Router's strategy configuration option
- 404
Description: Route not found
Path Parameters
- routeName (required)
-
string
Name of a route
Example 200 response data:
{
"bindAddress": "0.0.0.0",
"bindPort": 6446,
"clientConnectTimeoutInMs": 9000,
"destinationConnectTimeoutInMs": 15000,
"maxActiveConnections": 512,
"maxConnectErrors": 100,
"protocol": "classic",
"routingStrategy": "first-available"
}
GET
/routes/{routeName}/status
Get status of a route
Available Responses
- 200
-
Description: Status of a route
Response Schema
- activeConnections
-
integer
Number of active connections on the route
- totalConnections
-
integer
Number of connections handled by the route
- blockedHosts
-
integer
Number of blocked hosts
- 404
Description: Route not found
Example 200 response data:
{
"activeConnections": 1,
"totalConnections": 1,
"blockedHosts": 0
}
Path Parameters
- routeName (required)
-
string
Name of a route
GET
/routes/{routeName}/health
Get health of a route
Available Responses
- 200
-
Description: Health of a route
Response Schema
- isAlive
-
boolean
- 404
Description: Route not found
Path Parameters
- routeName (required)
-
string
Name of a route
Example 200 response data:
{
"isAlive": true
}
GET
/routes/{routeName}/destinations
Get destinations of a route
Available Responses
- 200
-
Description: Destinations of a route
Response Schema
- items
-
array
Contains 'address' (string, IP address of the destination node), and 'port' (integer, port of the destination node)
- 404
Description: Route not found
Path Parameters
- routeName (required)
-
string
Name of a route
Example 200 response data:
{
"items": [
{
"address": "127.0.0.1",
"port": 3320
},
{
"address": "127.0.0.1",
"port": 3330
}
]
}
GET
/routes/{routeName}/connections
Get connections of a route
Available Responses
- 200
-
Description: Connections of a route
Response Schema
- items
-
array
Each items entry contains the following:
bytesFromServer: integer, number of bytes sent from server to the client over the given connection
BytesToServer: integer, number of bytes sent from the client to the server over the given connection
sourceAddress: string, adddress:port pair of the connection source (client)
destinationAddress: string, adddress:port pair of the connection destination (server)
timeStarted: string, timepoint of the connection initialization
timeConnectedToServer: string, timepoint when the connection successfully established
timeLastSentToServer: string, timepoint when there was last data sent from client to server on the given connection
timeLastReceivedFromServer: string, timepoint when there was last data sent from server to client on the given connection
- 404
Description: Route not found
Path Parameters
- routeName (required)
-
string
Name of a route
Example 200 response data:
{
"items": [
{
"bytesFromServer": 2952,
"bytesToServer": 743,
"sourceAddress": "127.0.0.1:54098",
"destinationAddress": "127.0.0.1:3310",
"timeStarted": "2020-06-11T21:28:20.882204Z",
"timeConnectedToServer": "2020-06-11T21:28:20.882513Z",
"timeLastSentToServer": "2020-06-11T21:28:20.886969Z",
"timeLastReceivedFromServer": "2020-06-11T21:28:20.886968Z"
}
]
}
GET
/routes/{routeName}/blockedHosts
Get blocked host list for a route
Available Responses
- 200
-
Description: Blocked host list for a route
Response Schema
- items
-
array
IP addresses that are currently blocked by the routing core
- 404
Description: Route not found
Path Parameters
- routeName (required)
-
string
Name of a route
Example 200 response data:
{
"items": []
}
GET
/connection_pool/{name}/config
Shows maxIdleServerConnections as defined by
the max_idle_server_connection configuration
option. This is the maximum number (integer) of idling server
connections in the connection pool.
Shows idleTimeout as defined by the
idle_timeout configuration option. This is the
timeout in seconds (integer) before connections in the
connection pool are closed.
GET
/connection_pool/{name}/status
Shows reusedConnections as a count (integer)
of client connections that reused a server connection since the
application started.
Shows idleServerConnections as a count
(integer) of idling server connections currently in the
connection pool.
GET /swagger.json
Get a swagger (OpenAPI) file for the local REST API instance. Accessing the file does not require authentication; anyone with access to the REST API can generate and view it. The OpenAPI content depends on the active REST API plugins.
Example 200 response data:
{
"swagger": "2.0",
"info": {
"title": "MySQL Router",
"description": "API of MySQL Router",
"version": "20190715"
},
"basePath": "/api/20190715",
"tags": [
{
"name": "connectionpool",
"description": "Connection Pool"
},
{
"name": "cluster",
"description": "InnoDB Cluster"
},
{
"name": "app",
"description": "Application"
},
{
"name": "routes",
"description": "Routes"
}
],
"paths": {
"/connection_pool/{connectionPoolName}/status": {
"get": {
"tags": [
"connectionpool"
],
"description": "Get status of a route",
"responses": {
"200": {
"description": "status of a route",
"schema": {
"$ref": "#/definitions/ConnectionPoolStatus"
}
},
"404": {
"description": "route not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/connectionPoolNameParam"
}
]
},
"/connection_pool/{connectionPoolName}/config": {
"get": {
"tags": [
"connectionpool"
],
"description": "Get config of a route",
"responses": {
"200": {
"description": "config of a route",
"schema": {
"$ref": "#/definitions/ConnectionPoolConfig"
}
},
"404": {
"description": "route not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/connectionPoolNameParam"
}
]
},
"/connection_pool": {
"get": {
"tags": [
"connectionpool"
],
"description": "Get list of the connection pools",
"responses": {
"200": {
"description": "list of the connection pools",
"schema": {
"$ref": "#/definitions/ConnectionPoolList"
}
}
}
}
},
"/metadata/{metadataName}/config": {
"get": {
"tags": [
"cluster"
],
"description": "Get config of the metadata cache of a replicaset of a cluster",
"responses": {
"200": {
"description": "config of metadata cache",
"schema": {
"$ref": "#/definitions/MetadataConfig"
}
},
"404": {
"description": "cache not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/metadataNameParam"
}
]
},
"/metadata/{metadataName}/status": {
"get": {
"tags": [
"cluster"
],
"description": "Get status of the metadata cache of a replicaset of a cluster",
"responses": {
"200": {
"description": "status of metadata cache",
"schema": {
"$ref": "#/definitions/MetadataStatus"
}
},
"404": {
"description": "cache not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/metadataNameParam"
}
]
},
"/metadata": {
"get": {
"tags": [
"cluster"
],
"description": "Get list of the metadata cache instances",
"responses": {
"200": {
"description": "list of the metadata cache instances",
"schema": {
"$ref": "#/definitions/MetadataList"
}
}
}
}
},
"/router/status": {
"get": {
"tags": [
"app"
],
"description": "Get status of the application",
"responses": {
"200": {
"description": "status of application",
"schema": {
"$ref": "#/definitions/RouterStatus"
}
}
}
}
},
"/routing/status": {
"get": {
"tags": [
"routing"
],
"description": "Get status of the routing plugin",
"responses": {
"200": {
"description": "status of the routing plugin",
"schema": {
"$ref": "#/definitions/RoutingGlobalStatus"
}
}
}
}
},
"/routes/{routeName}/config": {
"get": {
"tags": [
"routes"
],
"description": "Get config of a route",
"responses": {
"200": {
"description": "config of a route",
"schema": {
"$ref": "#/definitions/RouteConfig"
}
},
"404": {
"description": "route not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/routeNameParam"
}
]
},
"/routes/{routeName}/status": {
"get": {
"tags": [
"routes"
],
"description": "Get status of a route",
"responses": {
"200": {
"description": "status of a route",
"schema": {
"$ref": "#/definitions/RouteStatus"
}
},
"404": {
"description": "route not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/routeNameParam"
}
]
},
"/routes/{routeName}/health": {
"get": {
"tags": [
"routes"
],
"description": "Get health of a route",
"responses": {
"200": {
"description": "health of a route",
"schema": {
"$ref": "#/definitions/RouteHealth"
}
},
"404": {
"description": "route not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/routeNameParam"
}
]
},
"/routes/{routeName}/destinations": {
"get": {
"tags": [
"routes"
],
"description": "Get destinations of a route",
"responses": {
"200": {
"description": "destinations of a route",
"schema": {
"$ref": "#/definitions/RouteDestinationList"
}
},
"404": {
"description": "route not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/routeNameParam"
}
]
},
"/routes/{routeName}/connections": {
"get": {
"tags": [
"routes"
],
"description": "Get connections of a route",
"responses": {
"200": {
"description": "connections of a route",
"schema": {
"$ref": "#/definitions/RouteConnectionsList"
}
},
"404": {
"description": "route not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/routeNameParam"
}
]
},
"/routes/{routeName}/blockedHosts": {
"get": {
"tags": [
"routes"
],
"description": "Get blocked host list for a route",
"responses": {
"200": {
"description": "blocked host list for a route",
"schema": {
"$ref": "#/definitions/RouteBlockedHostList"
}
},
"404": {
"description": "route not found"
}
}
},
"parameters": [
{
"$ref": "#/parameters/routeNameParam"
}
]
},
"/routes": {
"get": {
"tags": [
"routes"
],
"description": "Get list of the routes",
"responses": {
"200": {
"description": "list of the routes",
"schema": {
"$ref": "#/definitions/RouteList"
}
}
}
}
}
},
"definitions": {
"ConnectionPoolStatus": {
"type": "object",
"properties": {
"reusedServerConnections": {
"type": "integer"
},
"idleServerConnections": {
"type": "integer"
}
}
},
"ConnectionPoolConfig": {
"type": "object",
"properties": {
"idleTimeoutInMs": {
"type": "integer"
},
"maxIdleServerConnections": {
"type": "integer"
}
}
},
"ConnectionPoolSummary": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
},
"ConnectionPoolList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/ConnectionPoolSummary"
}
}
}
},
"MetadataStatus": {
"type": "object",
"properties": {
"lastRefreshHostname": {
"type": "string"
},
"lastRefreshPort": {
"type": "integer"
},
"timeLastRefreshFailed": {
"type": "string",
"format": "data-time"
},
"timeLastRefreshSucceeded": {
"type": "string",
"format": "data-time"
},
"refreshSucceeded": {
"type": "integer"
},
"refreshFailed": {
"type": "integer"
}
}
},
"MetadataConfig": {
"type": "object",
"properties": {
"clusterName": {
"type": "string"
},
"timeRefreshInMs": {
"type": "integer"
},
"groupReplicationId": {
"type": "string"
},
"nodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"hostname": {
"type": "string"
},
"port": {
"type": "integer"
}
}
}
}
}
},
"MetadataSummary": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
},
"MetadataList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/MetadataSummary"
}
}
}
},
"ClusterNodeSummary": {
"type": "object",
"properties": {
"groupUuid": {
"type": "string"
},
"serverUuid": {
"type": "string"
}
}
},
"ClusterNodeList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/ClusterNodeSummary"
}
}
}
},
"ClusterSummary": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
},
"ClusterList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/ClusterSummary"
}
}
}
},
"RouterStatus": {
"type": "object",
"properties": {
"timeStarted": {
"type": "string",
"format": "data-time"
},
"processId": {
"type": "integer"
},
"version": {
"type": "string"
},
"hostname": {
"type": "string"
},
"productEdition": {
"type": "string"
}
}
},
"RoutingGlobalStatus": {
"totalMaxConnections": "number of total connections allowed",
"currentMaxConnections": "number of current total connections"
},
"RouteHealth": {
"type": "object",
"properties": {
"isAlive": {
"type": "boolean"
}
}
},
"RouteStatus": {
"type": "object",
"properties": {
"activeConnections": {
"type": "integer"
},
"totalConnections": {
"type": "integer"
},
"blockedHosts": {
"type": "integer"
}
}
},
"RouteConfig": {
"type": "object",
"properties": {
"bindAddress": {
"type": "string"
},
"bindPort": {
"type": "integer"
},
"clientConnectTimeoutInMs": {
"type": "integer"
},
"destinationConnectTimeoutInMs": {
"type": "integer"
},
"maxActiveConnections": {
"type": "integer"
},
"maxConnectErrors": {
"type": "integer"
},
"protocol": {
"type": "string"
},
"socket": {
"type": "string"
},
"routingStrategy": {
"type": "string"
},
}
},
"RouteSummary": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
},
"RouteList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/RouteSummary"
}
}
}
},
"RouteDestinationSummary": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
},
"RouteDestinationList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/RouteDestinationSummary"
}
}
}
},
"RouteBlockedHostSummary": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
}
},
"RouteBlockedHostList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/RouteBlockedHostSummary"
}
}
}
},
"RouteConnectionsSummary": {
"type": "object",
"properties": {
"timeStarted": {
"type": "string",
"format": "date-time",
"description": "timepoint when connection to server was initiated"
},
"timeConnectedToServer": {
"type": "string",
"format": "date-time",
"description": "timepoint when connection to server succeeded"
},
"timeLastSentToServer": {
"type": "string",
"format": "date-time",
"description": "timepoint when there was last data sent from client to server"
},
"timeLastReceivedFromServer": {
"type": "string",
"format": "date-time",
"description": "timepoint when there was last data sent from server to client"
},
"bytesFromServer": {
"type": "integer",
"description": "bytes sent to destination"
},
"bytesToServer": {
"type": "integer",
"description": "bytes received from destination"
},
"destinationAddress": {
"type": "string",
"description": "address of the destination of the connection"
},
"sourceAddress": {
"type": "string",
"description": "address of the source of the connection"
}
}
},
"RouteConnectionsList": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/RouteConnectionsSummary"
}
}
}
}
},
"parameters": {
"connectionPoolNameParam": {
"name": "connectionPoolName",
"in": "path",
"description": "name of a connection pool",
"required": true,
"type": "string"
},
"metadataNameParam": {
"name": "metadataName",
"in": "path",
"description": "name of cluster",
"required": true,
"type": "string"
},
"clusterNameParam": {
"name": "clusterName",
"in": "path",
"description": "name of cluster",
"required": true,
"type": "string"
},
"routeNameParam": {
"name": "routeName",
"in": "path",
"description": "name of a route",
"required": true,
"type": "string"
}
}
}