WL#8965: REST interface

Affects: Server-8.0   —   Status: Complete


Understanding when the configured limits like max_connections are reached in the MySQL Router is currently not easily possible.

To make it easier, the Router needs an interface that exposes internal data to the user in a machine readable/human friendly format.


Utilize WL#11891 and exposes data as REST endpoints via HTTP methods as JSON payload.

Allow monitoring applications/users structured access to:

  • configuration data
  • performance information
  • resource usage

Design Requirements

The REST API should follow REST API guidelines like the ones for OCI:

  • APIs specified in OpenAPI 2.0
  • API version SHOULD be numeric and align with release date
  • Naming Rules
    • CamelCase
    • boolean valures: is...
  • Error messages SHOULD follow RFC7807
  • return objects for List operations
  • Unknown parameters SHOULD lead to HTTP status 400, "InvalidParameter"

Functional Requirements

REST endpoints MUST respond to HTTP methods they don't support with "405 Method not allowed"
REST endpoints with sensitive information MUST be authenticated.
Content-Type of each response to REST API request SHOULD at least support "application/json".
Interface Description of all REST endpoints MUST written in OpenAPI 2.0
Interface Description of all REST endpoints MUST be fetchable as /api/{versionToken}/swagger.json

Interface Definition

REST endpoints define

  • a URL pattern
  • HTTP methods they support
  • parameters they understand
  • format of the responses they send as response
  • if authentication is required

On the other side, a web-browser or any HTTP client can be used to get operate on REST APIs if the specified interfaces are followed.


OpenAPI allows to specify REST endpoints and allows to generate client code easily.

Base Path

The base-path of all REST Endpoints is:


which is followed by a "version token" like 20190715:


to allow multiple APIs be supported in parallel.

Behaviour for dependent Worklogs

unsupported HTTP methods

Each REST endpoints has a supported set of HTTP methods like

  • GET and HEAD
  • PUT
  • POST

Requests for a HTTP methods that's not supported by a resource MUST be answered with HTTP Status "405", aka "method not allowed".

Authentication Required

Resources that require authentication MUST response with HTTP Status "401", aka "authentication required" if the request is not authenticated or authentication failed.


Content Type for all responses SHOULD be application/json.

Implementations may also support other content-types like text/html if they want to send HTML instead of JSON.


rest_api plugin

The rest-api plugin provides the foundation and must be loaded:


It requires the http_server plugin being loaded.

config options

  • require_realm, string, optional, name of a authentication realm (WL#12503)


When the rest_api plugin is loaded, it exposes a swagger.json that can be fetched with GET.

GET /api/{versionToken}/swagger.json HTTP/1.1 serves a JSON file that conforms to the openapi 2.0 spec.

is sent