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 |
---|---|---|---|
/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 /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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "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" } } }