6.2 MySQL Router REST API Reference

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

metadata

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
}

router

GET /router/status

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

routes

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": []
}

connection_pool

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.

swagger.json

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