Documentation Home
MySQL Router 8.0
Related Documentation Download this Manual
PDF (US Ltr) - 0.6Mb
PDF (A4) - 0.6Mb


MySQL Router 8.0  / MySQL Router REST API  /  MySQL Router REST API Reference

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". SeeSection 6.1, “A Simple MySQL Router REST API Guide” for related information.

Table 6.1 MySQL Router REST API Endpoints

EndpointDescriptionPluginMethod
/metadataGet metadata instance namesrest_metadata_cacheGET
/metadata/{metadataName}/configGet metadata configuration detailsrest_metadata_cacheGET
/metadata/{metadataName}/statusCheck metadata statusrest_metadata_cacheGET
/router/statusCheck Router statusrest_routerGET
/routesGet list of routesrest_routingGET
/routes/{routeName}/blockedHostsGet list of blocked IPsrest_routingGET
/routes/{routeName}/configGet route configuration detailsrest_routingGET
/routes/{routeName}/connectionsGet route connectionsrest_routingGET
/routes/{routeName}/destinationsGet route destinationsrest_routingGET
/routes/{routeName}/healthCheck route healthrest_routingGET
/routes/{routeName}/statusCheck route statusrest_routingGET
/connection_pool/{name}/configCheck connection_pool configrest_connection_poolGET
/connection_pool/{name}/statusCheck connection_pool statusrest_connection_poolGET
swagger.jsonGet swagger file containing available paths and informationrest_apiGET

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

mode

string

The mode used; such as "read-write" or "read-only" as defined by Router's mode 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

ShowsmaxIdleServerConnections as defined by themax_idle_server_connection configuration option. This is the maximum number (integer) of idling server connections in the connection pool.

ShowsidleTimeout as defined by theidle_timeout configuration option. This is the timeout in seconds (integer) before connections in the connection pool are closed.

GET/connection_pool/{name}/status

ShowsreusedConnections as a count (integer) of client connections that reused a server connection since the application started.

ShowsidleServerConnections as a count (integer) of idling server connections currently in the connection pool.

Therest_connection_pool functionality was added in MySQL Router 8.0.29.

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"        },        "mode": {          "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"    }  }}