6.1 A Simple MySQL Router REST API Guide

This guide sets up a basic Router REST API, adds basic authentication, and exposes a route to check Router's status. The REST API is configured using configuration sections and options are required to enable and use the REST API. For example, here's a minimal MySQL Router configuration file that enables the most basic REST API functionality:

[DEFAULT]
logging_folder=

# Exposes http://127.0.0.1:8081
[http_server]

# Exposes /api/20190715/swagger.json
[rest_api]

A typical Router configuration file contains other options but this guide focuses on the REST API. Save this file (our guide assumes (/foo/mysqlrouter.conf), start Router loading this file (such as mysqlrouter -c /foo/mysqlrouter.conf, and confirm that http://127.0.0.1:8081/api/20190715/swagger.json exists. Example swagger.json content:

{
  "swagger": "2.0",
  "info": {
    "title": "MySQL Router",
    "description": "API of MySQL Router",
    "version": "20190715"
  },
  "basePath": "/api/20190715",
  "tags": [],
  "paths": {},
  "definitions": {}
}

This demonstrates that the Router REST API plugin is loaded, and that additional plugins exposing routes and paths are not enabled. Authentication is not required to retrieve swagger.json.

Note

The API version number may change in a future release; and future releases may include functionality to retrieve this API integer.

Next, let's enable the simple rest_router plugin to expose the router/status path. Authentication is required, and enabling authentication requires additional configuration options. For example:

[DEFAULT]
logging_folder=

# Exposes http://127.0.0.1:8081
[http_server]

# Exposes /api/20190715/swagger.json
[rest_api]

# Exposes /api/20190715/router/status
[rest_router]
require_realm=somerealm

# Exposes /api/20190715/routes/*
#[rest_routing]
#require_realm=somerealm

# Exposes /api/20190715/metadata/*
#[rest_metadata_cache]
#require_realm=somerealm

# Define our realm
[http_auth_realm:somerealm]
backend=somebackend
method=basic
name=Some Realm

# Define our backend; this file must exist and validate
[http_auth_backend:somebackend]
backend=file
filename=/etc/mysqlrouter/mysqlrouter.pwd

Router uses realms for authentication, and the mysqlrouter_passwd command-line utility generates and manages these users. For example, this creates a user named someuser and saves it as a new file named /etc/mysqlrouter/mysqlrouter.pwd:

# Generate and save the user/pass
$> mysqlrouter_passwd set /etc/mysqlrouter/mysqlrouter.pwd someuser
Please enter password:

# Optionally list usernames and salted passwords in the file:
$> mysqlrouter_passwd list /etc/mysqlrouter/mysqlrouter.pwd

someuser:$5$43tfYEwobPBLkYDB$XnHyC0uXY1F4f6ryd8Vj5CUnEqcH3tqf4pud9kqIji3

Restarting Router with our new configuration file generates a different swagger.json that now contains [rest_router] plugin information for its /router/status route:

{
  "swagger": "2.0",
  "info": {
    "title": "MySQL Router",
    "description": "API of MySQL Router",
    "version": "20190715"
  },
  "basePath": "/api/20190715",
  "tags": [
    {
      "name": "app",
      "description": "Application"
    }
  ],
  "paths": {
    "/router/status": {
      "get": {
        "tags": [
          "app"
        ],
        "description": "Get status of the application",
        "responses": {
          "200": {
            "description": "status of application",
            "schema": {
              "$ref": "#/definitions/RouterStatus"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "RouterStatus": {
      "type": "object",
      "properties": {
        "timeStarted": {
          "type": "string",
          "format": "data-time"
        },
        "processId": {
          "type": "integer"
        },
        "version": {
          "type": "string"
        },
        "hostname": {
          "type": "string"
        },
        "productEdition": {
          "type": "string"
        }
      }
    }
  }
}

Loading http://127.0.0.1:8081/api/20190715/router/status prompts for a username and password (that we created in our example) and on success returns Router's current status. For example:

{
  "processId": 1883,
  "productEdition": "MySQL Community - GPL",
  "timeStarted": "2022-01-25T21:23:50.442399Z",
  "version": "8.0.40",
  "hostname": "boat"
}

We set up a basic Router REST API with an authenticated backend; a REST API with two of the REST API plugins enabled.