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:
Press CTRL+C to copy[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:
Press CTRL+C to copy{ "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
.
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:
Press CTRL+C to copy[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
:
Press CTRL+C to copy# 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:
Press CTRL+C to copy{ "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:
Press CTRL+C to copy{ "processId": 1883, "productEdition": "MySQL Community - GPL", "timeStarted": "2022-01-25T21:23:50.442399Z", "version": "8.4.4", "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.