Motivation

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.

Goals

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

FR1

REST endpoints MUST respond to HTTP methods they don't support with "405 Method not allowed"

FR2

REST endpoints with sensitive information MUST be authenticated.

FR3

Content-Type of each response to REST API request SHOULD at least support "application/json".

FR4

Interface Description of all REST endpoints MUST written in OpenAPI 2.0

FR5

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

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

Base Path

The base-path of all REST Endpoints is:

/api/

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

/api/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
• DELETE

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

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.

Implementation

rest_api plugin

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

[rest_api]

It requires the http_server plugin being loaded.

config options

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

swagger.json

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.

Content-Type

application/json

Last-Modified

is sent