From 3998a6e4697f14003f0a603db09cf8cb5d4def18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Wed, 3 Oct 2018 16:42:11 +0300 Subject: [PATCH] Update REST API documentation Updated and unified the documentation of the REST API. --- Documentation/REST-API/API.md | 8 +- Documentation/REST-API/Resources-Filter.md | 3 +- Documentation/REST-API/Resources-MaxScale.md | 82 ++++++++++---------- Documentation/REST-API/Resources-Monitor.md | 76 +++++++++++------- Documentation/REST-API/Resources-Server.md | 30 ++++--- Documentation/REST-API/Resources-Service.md | 62 +++++++++------ Documentation/REST-API/Resources-Session.md | 9 ++- Documentation/REST-API/Resources-User.md | 76 +++++++++--------- 8 files changed, 195 insertions(+), 151 deletions(-) diff --git a/Documentation/REST-API/API.md b/Documentation/REST-API/API.md index f5db82172..c383b9e61 100644 --- a/Documentation/REST-API/API.md +++ b/Documentation/REST-API/API.md @@ -136,9 +136,9 @@ by this API. Credentials for authentication. This header should consist of a HTTP Basic Access authentication type payload which is the base64 encoded value of the username and password joined by a colon e.g. `Base64("maxuser:maxpwd")`. The -REST API uses the same users as the MaxAdmin interface. For more details about -MaxScale administrative users, refer to the [MaxAdmin](../Reference/MaxAdmin.md) -documentation. +REST API uses the same users as the MaxAdmin network interface. For more details +about MaxScale administrative users, refer to the +[MaxAdmin](../Reference/MaxAdmin.md) documentation. #### Content-Type @@ -146,7 +146,7 @@ All PUT and POST requests must use the `Content-Type: application/json` media type and the request body must be a complete and valid JSON representation of a resource. All PATCH requests must use the `Content-Type: application/json` media type and the request body must be a JSON document containing a partial -definition of the original resource. +definition of the modified resource. #### Host diff --git a/Documentation/REST-API/Resources-Filter.md b/Documentation/REST-API/Resources-Filter.md index d6c0a8820..b2dd22374 100644 --- a/Documentation/REST-API/Resources-Filter.md +++ b/Documentation/REST-API/Resources-Filter.md @@ -111,8 +111,7 @@ As the service to filter relationship is ordered (filters are applied in the order they are listed), filter to service relationships cannot be defined at creation time. -The following example defines a request body which creates the new filter, -_test-filter_, and assigns it to a service. +The following example defines a request body which creates a new filter. ```javascript { diff --git a/Documentation/REST-API/Resources-MaxScale.md b/Documentation/REST-API/Resources-MaxScale.md index 35ca0a076..b159ff668 100644 --- a/Documentation/REST-API/Resources-MaxScale.md +++ b/Documentation/REST-API/Resources-MaxScale.md @@ -7,13 +7,13 @@ of which the modules build upon. ## Get global information -Retrieve global information about a MaxScale instance. This includes various -file locations, configuration options and version information. - ``` GET /v1/maxscale ``` +Retrieve global information about a MaxScale instance. This includes various +file locations, configuration options and version information. + #### Response `Status: 200 OK` @@ -67,6 +67,10 @@ GET /v1/maxscale ## Update MaxScale parameters +``` +PATCH /v1/maxscale +``` + Update MaxScale parameters. The request body must define updated values for the `data.attributes.parameters` object. The following parameters can be altered: @@ -77,10 +81,6 @@ Update MaxScale parameters. The request body must define updated values for the - [admin_log_auth_failures](../Getting-Started/Configuration-Guide.md#admin_log_auth_failures) - [passive](../Getting-Started/Configuration-Guide.md#passive) -``` -PATCH /v1/maxscale -``` - #### Response Parameters modified: @@ -93,14 +93,14 @@ Invalid JSON body: ## Get thread information -Get the information and statistics of a particular thread. The _:id_ in -the URI must map to a valid thread number between 0 and the configured -value of `threads`. - ``` GET /v1/maxscale/threads/:id ``` +Get the information and statistics of a particular thread. The _:id_ in +the URI must map to a valid thread number between 0 and the configured +value of `threads`. + #### Response `Status: 200 OK` @@ -143,12 +143,12 @@ GET /v1/maxscale/threads/:id ## Get information for all threads -Get the informatino for all threads. Returns a collection of threads resources. - ``` GET /v1/maxscale/threads ``` +Get the information for all threads. Returns a collection of threads resources. + #### Response `Status: 200 OK` @@ -277,13 +277,13 @@ GET /v1/maxscale/threads ## Get logging information -Get information about the current state of logging, enabled log files and the -location where the log files are stored. - ``` GET /v1/maxscale/logs ``` +Get information about the current state of logging, enabled log files and the +location where the log files are stored. + #### Response `Status: 200 OK` @@ -326,14 +326,14 @@ GET /v1/maxscale/logs ## Update logging parameters -Update logging parameters. The request body must define updated values for the -`data.attributes.parameters` object. All logging parameters apart from -`log_to_shm` can be altered at runtime. - ``` PATCH /v1/maxscale/logs ``` +Update logging parameters. The request body must define updated values for the +`data.attributes.parameters` object. All logging parameters apart from +`log_to_shm` can be altered at runtime. + #### Response Parameters modified: @@ -346,25 +346,25 @@ Invalid JSON body: ## Flush and rotate log files -Flushes any pending messages to disk and reopens the log files. The body of the -message is ignored. - ``` POST /v1/maxscale/logs/flush ``` +Flushes any pending messages to disk and reopens the log files. The body of the +message is ignored. + #### Response `Status: 204 No Content` ## Get task schedule -Retrieve all pending tasks that are queued for execution. - ``` GET /v1/maxscale/tasks ``` +Retrieve all pending tasks that are queued for execution. + #### Response `Status: 200 OK` @@ -378,15 +378,15 @@ GET /v1/maxscale/tasks } ``` -## Get loaded modules - -Retrieve information about a loaded module. This includes version, API and -maturity information as well as all the parameters that the module defines. +## Get a loaded module ``` -GET /v1/maxscale/modules +GET /v1/maxscale/modules/:name ``` +Retrieve information about a loaded module. The _:name_ must be the name of a +valid loaded module. + #### Response `Status: 200 OK` @@ -467,12 +467,12 @@ GET /v1/maxscale/modules ## Get all loaded modules -Retrieve information about all loaded modules. - ``` GET /v1/maxscale/modules ``` +Retrieve information about all loaded modules. + #### Response `Status: 200 OK` @@ -519,15 +519,6 @@ GET /v1/maxscale/modules ## Call a module command -Modules can expose commands that can be called via the REST API. The module -resource lists all commands in the `data.attributes.commands` list. Each value -is a command sub-resource identified by its `id` field and the HTTP method the -command uses is defined by the `attributes.method` field. - -The _:module_ in the URI must be a valid name of a loaded module and _:command_ -must be a valid command identifier that is exposed by that module. All -parameters to the module commands are passed as HTTP request parameters. - For read-only commands: ``` @@ -540,6 +531,15 @@ For commands that can modify data: POST /v1/maxscale/modules/:module/:command ``` +Modules can expose commands that can be called via the REST API. The module +resource lists all commands in the `data.attributes.commands` list. Each value +is a command sub-resource identified by its `id` field and the HTTP method the +command uses is defined by the `attributes.method` field. + +The _:module_ in the URI must be a valid name of a loaded module and _:command_ +must be a valid command identifier that is exposed by that module. All +parameters to the module commands are passed as HTTP request parameters. + Here is an example POST requests to the dbfwfilter module command _reload_ with two parameters, the name of the filter instance and the path to a file: diff --git a/Documentation/REST-API/Resources-Monitor.md b/Documentation/REST-API/Resources-Monitor.md index 8f847a10f..49988c8e3 100644 --- a/Documentation/REST-API/Resources-Monitor.md +++ b/Documentation/REST-API/Resources-Monitor.md @@ -7,13 +7,13 @@ more servers. ### Get a monitor -Get a single monitor. The _:name_ in the URI must be a valid monitor name with -all whitespace replaced with hyphens. The monitor names are case-sensitive. - ``` GET /v1/monitors/:name ``` +Get a single monitor. The _:name_ in the URI must be a valid monitor name with +all whitespace replaced with hyphens. The monitor names are case-sensitive. + #### Response `Status: 200 OK` @@ -110,12 +110,12 @@ GET /v1/monitors/:name ### Get all monitors -Get all monitors. - ``` GET /v1/monitors ``` +Get all monitors. + #### Response `Status: 200 OK` @@ -214,19 +214,33 @@ GET /v1/monitors ### Create a monitor -Create a new monitor. The request body must define the `/data/id` -field with the name of the monitor, the `/data/type` field with the -value of `monitors` and the `/data/attributes/module` field with the -monitor module for this monitor. All of the monitor parameters can -be defined at creation time. - ``` POST /v1/monitors ``` -The following example defines a request body which creates the new monitor, -_test-monitor_, and assigns two servers to be monitored by it. It also defines -a custom value for the _monitor_interval_ parameter. +Create a new monitor. The request body must define at least the following +fields. + +* `data.id` + * Name of the monitor + +* `data.type` + * Type of the object, must be `monitors` + +* `data.attributes.module` + * The monitor module to use + +* `data.attributes.parameters.user` + * The [`user`](../Getting-Started/Configuration-Guide.md#password) to use + +* `data.attributes.parameters.password` + * The [`password`](../Getting-Started/Configuration-Guide.md#password) to use + +All monitor parameters can be defined at creation time. + +The following example defines a request body which creates a new monitor and +assigns two servers to be monitored by it. It also defines a custom value for +the _monitor_interval_ parameter. ```javascript { @@ -236,7 +250,9 @@ a custom value for the _monitor_interval_ parameter. "attributes": { "module": "mariadbmon", // The monitor uses the mariadbmon module "parameters": { // Monitor parameters - "monitor_interval": 1000 + "monitor_interval": 1000, + "user": "maxuser, + "password": "maxpwd" } }, "relationships": { // List of server relationships that this monitor uses @@ -265,16 +281,18 @@ Monitor is created: ### Update a monitor -The :name in the URI must map to a monitor name with all whitespace replaced with -hyphens. The request body must be a valid JSON document representing the modified monitor. - ``` PATCH /v1/monitors/:name ``` +The :name in the URI must map to a monitor name with all whitespace replaced +with hyphens. The request body must be a valid JSON document representing the +modified monitor. + ### Modifiable Fields The following standard server parameter can be modified. + - [user](../Monitors/Monitor-Common.md#user) - [password](../Monitors/Monitor-Common.md#password) - [monitor_interval](../Monitors/Monitor-Common.md#monitor_interval) @@ -283,10 +301,9 @@ The following standard server parameter can be modified. - [backend_read_timeout](../Monitors/Monitor-Common.md#backend_read_timeout) - [backend_connect_attempts](../Monitors/Monitor-Common.md#backend_connect_attempts) -Refer to the documentation on these parameters for valid values. - -In addition to these standard parameters, the monitor specific parameters can also be -modified. Refer to the monitor module documentation for details on these parameters. +In addition to these standard parameters, the monitor specific parameters can +also be modified. Refer to the monitor module documentation for details on these +parameters. #### Response @@ -348,14 +365,13 @@ Invalid JSON body: ### Destroy a monitor -Destroy a created monitor. The monitor must not have relationships to any -servers and if it does a PATCH request which removes these relationships is -required before a DELETE request for the monitor can be made. - ``` DELETE /v1/monitors/:name/stop ``` +Destroy a created monitor. The monitor must not have relationships to any +servers in order to be destroyed. + #### Response Monitor is deleted: @@ -368,12 +384,12 @@ Monitor could not be deleted: ### Stop a monitor -Stops a started monitor. - ``` PUT /v1/monitors/:name/stop ``` +Stops a started monitor. + #### Response Monitor is stopped: @@ -382,12 +398,12 @@ Monitor is stopped: ### Start a monitor -Starts a stopped monitor. - ``` PUT /v1/monitors/:name/start ``` +Starts a stopped monitor. + #### Response Monitor is started: diff --git a/Documentation/REST-API/Resources-Server.md b/Documentation/REST-API/Resources-Server.md index 7e5231925..c9acaaff1 100644 --- a/Documentation/REST-API/Resources-Server.md +++ b/Documentation/REST-API/Resources-Server.md @@ -232,11 +232,23 @@ Response contains a resource collection with all servers. POST /v1/servers ``` -Create a new server by defining the resource. The posted object must define the -_data.id_ field with the name of the server and the -_data.atttributes.parameters_ field with JSON object containing values for the -_address_ and _port_ parameters. The following is the minimal required JSON -object for defining a new server. +Create a new server by defining the resource. The posted object must define at +least the following fields. + +* `data.id` + * Name of the server + +* `data.type` + * Type of the object, must be `servers` + +* `data.attributes.parameters.address` + * The [`address`](../Getting-Started/Configuration-Guide.md#address) to use + +* `data.attributes.parameters.port` + * The [`port`](../Getting-Started/Configuration-Guide.md#port) to use + + +The following is the minimal required JSON object for defining a new server. ```javascript { @@ -246,8 +258,7 @@ object for defining a new server. "attributes": { "parameters": { "address": "127.0.0.1", - "port": 3003, - "protocol": "MariaDBBackend" + "port": 3003 } } } @@ -265,8 +276,7 @@ new servers to be created and immediately taken into use. "attributes": { "parameters": { "address": "127.0.0.1", - "port": 3002, - "protocol": "MariaDBBackend" + "port": 3002 } }, "relationships": { @@ -301,12 +311,12 @@ The following parameters can be defined when a server is being created. - [port](../Getting-Started/Configuration-Guide.md#port) - [protocol](../Getting-Started/Configuration-Guide.md#protocol) - [authenticator](../Getting-Started/Configuration-Guide.md#authenticator) -- [authenticator_options](../Getting-Started/Configuration-Guide.md#authenticator-options) - [ssl_key](../Getting-Started/Configuration-Guide.md#ssl_key) - [ssl_cert](../Getting-Started/Configuration-Guide.md#ssl_cert) - [ssl_ca_cert](../Getting-Started/Configuration-Guide.md#ssl_ca_cert) - [ssl_version](../Getting-Started/Configuration-Guide.md#ssl_version) - [ssl_cert_verify_depth](../Getting-Started/Configuration-Guide.md#ssl_cert_verify_depth) +- [ssl_verify_peer_certificate](../Getting-Started/Configuration-Guide.md#ssl_verify_peer_certificate) #### Response diff --git a/Documentation/REST-API/Resources-Service.md b/Documentation/REST-API/Resources-Service.md index 62f6dfabf..9615eb3d5 100644 --- a/Documentation/REST-API/Resources-Service.md +++ b/Documentation/REST-API/Resources-Service.md @@ -7,13 +7,13 @@ collection of network listeners, filters, a router and a set of backend servers. ### Get a service -Get a single service. The _:name_ in the URI must be a valid service name with -all whitespace replaced with hyphens. The service names are case-insensitive. - ``` GET /v1/services/:name ``` +Get a single service. The _:name_ in the URI must be a valid service name with +all whitespace replaced with hyphens. The service names are case-insensitive. + #### Response `Status: 200 OK` @@ -88,12 +88,12 @@ GET /v1/services/:name ### Get all services -Get all services. - ``` GET /v1/services ``` +Get all services. + #### Response `Status: 200 OK` @@ -239,13 +239,13 @@ least the following fields. * `data.type` * Type of the object, must be `services` -* `data.atttributes.router` +* `data.attributes.router` * The router module to use -* `data.atttributes.parameters.user` +* `data.attributes.parameters.user` * The [`user`](../Getting-Started/Configuration-Guide.md#password) to use -* `data.atttributes.parameters.password` +* `data.attributes.parameters.password` * The [`password`](../Getting-Started/Configuration-Guide.md#password) to use The `data.attributes.parameters` object is used to define router and service @@ -377,14 +377,14 @@ GET /v1/services/:name/listeners ### Get a single service listener -Get the listeners of a service. The _:name_ in the URI must be a valid service -name and _:listener_ must be a valid listener name, both with all whitespace -replaced with hyphens. - ``` GET /v1/services/:name/listeners/:listener ``` +Get the listeners of a service. The _:name_ in the URI must be a valid service +name and _:listener_ must be a valid listener name, both with all whitespace +replaced with hyphens. + #### Response `Status: 200 OK` @@ -410,7 +410,6 @@ GET /v1/services/:name/listeners/:listener ### Create a new listener - ``` POST /v1/services/:name/listeners ``` @@ -479,13 +478,13 @@ Listener cannot be deleted: ### Update a service -The _:name_ in the URI must map to a service name and the request body must be a -valid JSON Patch document which is applied to the resource. - ``` PATCH /v1/services/:name ``` +The _:name_ in the URI must map to a service name and the request body must be a +JSON object which is interpreted as the new definition of the service. + All standard service parameters can be modified. Refer to the [service](../Getting-Started/Configuration-Guide.md#service) documentation on the details of these parameters. @@ -495,6 +494,20 @@ at runtime if the router module supports it. Refer to the individual router documentation for more details on whether the router supports it and which parameters can be updated at runtime. +The following example modifies a service by changing the `user` parameter to `admin`. + +```javascript +{ + "data": { + "attributes": { + "parameters": { + "user": "admin" + } + } + } +} +``` + #### Response Service is modified: @@ -504,12 +517,12 @@ Service is modified: ### Update service relationships ``` -PATCH /v1/services/:name/relationships/servers -PATCH /v1/services/:name/relationships/filters +PATCH /v1/services/:name/relationships/:type ``` The _:name_ in the URI must map to a service name with all whitespace replaced -with hyphens. +with hyphens. The _:type_ in the URI must be either _servers_ or _filters_, +depending on which relationship is being modified. The request body must be a JSON object that defines only the _data_ field. The value of the _data_ field must be an array of relationship objects that define @@ -524,7 +537,8 @@ existing relationships of this type for the service. Both `servers` and for more details. The following is an example request and request body that defines a single -server relationship for a service. +server relationship for a service that is equivalent to a `servers=my-server` +parameter. ``` PATCH /v1/services/my-rw-service/relationships/servers @@ -560,12 +574,12 @@ Invalid JSON body: ### Stop a service -Stops a started service. - ``` PUT /v1/services/:name/stop ``` +Stops a started service. + #### Response Service is stopped: @@ -574,12 +588,12 @@ Service is stopped: ### Start a service -Starts a stopped service. - ``` PUT /v1/services/:name/start ``` +Starts a stopped service. + #### Response Service is started: diff --git a/Documentation/REST-API/Resources-Session.md b/Documentation/REST-API/Resources-Session.md index 76e188648..fc94afc03 100644 --- a/Documentation/REST-API/Resources-Session.md +++ b/Documentation/REST-API/Resources-Session.md @@ -8,12 +8,13 @@ session is created on a service and each service can have multiple sessions. ### Get a session -Get a single session. _:id_ must be a valid session ID. - ``` GET /v1/sessions/:id ``` +Get a single session. _:id_ must be a valid session ID. The session ID is the +same that is exposed to the client as the connection ID. + #### Response `Status: 200 OK` @@ -55,12 +56,12 @@ GET /v1/sessions/:id ### Get all sessions -Get all sessions. - ``` GET /v1/sessions ``` +Get all sessions. + #### Response `Status: 200 OK` diff --git a/Documentation/REST-API/Resources-User.md b/Documentation/REST-API/Resources-User.md index 7a1946745..f10546cfe 100644 --- a/Documentation/REST-API/Resources-User.md +++ b/Documentation/REST-API/Resources-User.md @@ -7,13 +7,13 @@ MaxScale's configuration. ### Get network user -Get a single network user. The The _:name_ in the URI must be a valid network -user name. - ``` GET /v1/users/inet/:name ``` +Get a single network user. The The _:name_ in the URI must be a valid network +user name. + #### Response `Status: 200 OK` @@ -38,12 +38,12 @@ GET /v1/users/inet/:name ### Get all network users -Get all network users. - ``` GET /v1/users/inet ``` +Get all network users. + #### Response `Status: 200 OK` @@ -70,13 +70,13 @@ GET /v1/users/inet ### Get enabled UNIX account -Get a single enabled UNIX account. The The _:name_ in the URI must be a valid -UNIX account name that has been enabled. - ``` GET /v1/users/unix/:name ``` +Get a single enabled UNIX account. The The _:name_ in the URI must be a valid +UNIX account name that has been enabled. + #### Response `Status: 200 OK` @@ -101,12 +101,12 @@ GET /v1/users/unix/:name ### Get all enabled UNIX accounts -Get all enabled UNIX accounts. - ``` GET /v1/users/unix ``` +Get all enabled UNIX accounts. + #### Response `Status: 200 OK` @@ -133,13 +133,13 @@ GET /v1/users/unix ### Get all users -Get all administrative users. This fetches both network users and local UNIX -accounts. - ``` GET /v1/users ``` +Get all administrative users. This fetches both network users and local UNIX +accounts. + #### Response `Status: 200 OK` @@ -176,21 +176,24 @@ GET /v1/users ### Create a network user -Create a new network user. - ``` POST /v1/users/inet ``` -The request body must fulfill the following requirements. +Create a new network user. The request body must define at least the +following fields. -- The `/data/id`, `/data/type`, `/data/attributes/account` and - `/data/attributes/password` fields must be defined. -- The `/data/id` field defines the name of the account -- The `/data/attributes/password` field defines the password for this user. -- The `/data/attributes/account` field should be set to `admin` for - administrative users and `basic` to read-only users. -- The value of the `/data/type` field must always be `inet`. +* `data.id` + * The username + +* `data.type` + * Type of the object, must be `inet` + +* `data.attributes.password` + * The password for this user + +* `data.attributes.account` + * Set to `admin` for administrative users and `basic` to read-only users Here is an example request body defining the network user _my-user_ with the password _my-password_ that is allowed to execute only read-only operations. @@ -216,20 +219,21 @@ Status: 204 No Content ### Enable a UNIX account -This enables an existing UNIX account on the system for administrative -operations. - ``` POST /v1/users/unix ``` -The request body must fulfill the following requirements. +This enables an existing UNIX account on the system for administrative +operations. The request body must define at least the following fields. -- The `/data/id`, `/data/type` and `/data/attributes/account` fields must be defined. -- The `/data/id` field defines the name of the account -- The `/data/attributes/account` field should be set to `admin` for - administrative users and `basic` to read-only users. -- The value of the `/data/type` field must always be `unix`. +* `data.id` + * The username + +* `data.type` + * Type of the object, must be `unix` + +* `data.attributes.account` + * Set to `admin` for administrative users and `basic` to read-only users Here is an example request body enabling the UNIX account _jdoe_ for read-only operations. @@ -253,12 +257,12 @@ Status: 204 No Content ### Delete a network user -The _:name_ part of the URI must be a valid user name. - ``` DELETE /v1/users/inet/:name ``` +The _:name_ part of the URI must be a valid user name. + #### Response ``` @@ -267,12 +271,12 @@ Status: 204 No Content ### Disable a UNIX account -The _:name_ part of the URI must be a valid user name. - ``` DELETE /v1/users/unix/:name ``` +The _:name_ part of the URI must be a valid user name. + #### Response ```