From c1a1f18d1ae21a071b8eb43c5490a81783b2e3f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Tue, 2 May 2017 14:53:25 +0300 Subject: [PATCH] MXS-1220: Update server resource documentation Updated server resource documentation with new output and updated instructions on how to modify servers via the REST API. --- .../Getting-Started/Configuration-Guide.md | 2 +- Documentation/REST-API/API.md | 59 +++++ Documentation/REST-API/Resources-Server.md | 240 +++++++++++++----- 3 files changed, 240 insertions(+), 61 deletions(-) diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index b7d22f438..086a939dc 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -536,7 +536,7 @@ interfaces. #### `admin_port` The port where the HTTP admin interface listens on. The default value is port -8080. +8989. #### `admin_auth` diff --git a/Documentation/REST-API/API.md b/Documentation/REST-API/API.md index afa08573b..c9a7b6010 100644 --- a/Documentation/REST-API/API.md +++ b/Documentation/REST-API/API.md @@ -15,6 +15,12 @@ This document describes the version 1 of the MaxScale REST API. - [Resources](#resources) - [Common Request Parameter](#common-request-parameters) +## Note About Syntax + +Although JSON does not define a syntax for comments, some of the JSON examples +have C-style inline comments in them. These comments use `//` to mark the start +of the comment and extend to the end of the current line. + ## HTTP Headers ### Request Headers @@ -421,12 +427,65 @@ The MaxScale REST API provides the following resources. - [/sessions](Resources-Session.md) - [/users](Resources-User.md) +### Resource Relationships + +All resources return complete JSON objects. The returned objects can have a +_relationships_ field that represents any relations the object has to other +objects. This closely resembles the JSON API definition of links. + +In the _relationships_ objects, all resources have a _self_ link that points to +the resource itself. This allows for easier updating of resources as the reply +URL is included in the request itself. + +The following lists the resources and the types of links each resource can have +in addition to the _self_ link. + +- `services` - Service resource + + - `servers` + + List of servers used by the service + + - `filters` + + List of filters used by the service + +- `monitors` - Monitor resource + + - `servers` + + List of servers used by the monitor + +- `filters` - Filter resource + + - `services` + + List of services that use this filter + +- `servers` - Server resource + + - `services` + + List of services that use this server + + - `monitors` + + List of monitors that use this server + ## Common Request Parameters Most of the resources that support GET also support the following parameters. See the resource documentation for a list of supported request parameters. +- `pretty` + + - Pretty-print output. + + If this parameter is set to `true` then the returned objects are + formatted in a more human readable format. All resources support this + parameter. + - `fields` - A list of fields to return. diff --git a/Documentation/REST-API/Resources-Server.md b/Documentation/REST-API/Resources-Server.md index a73b0d531..9fd9b28a1 100644 --- a/Documentation/REST-API/Resources-Server.md +++ b/Documentation/REST-API/Resources-Server.md @@ -19,17 +19,36 @@ GET /servers/:name Status: 200 OK { - "name": "db-serv-1", - "address": "192.168.121.58", - "port": 3306, - "protocol": "MySQLBackend", - "status": [ - "master", - "running" - ], + "name": "server1", "parameters": { - "report_weight": 10, - "app_weight": 2 + "address": "127.0.0.1", + "port": 3000, + "protocol": "MySQLBackend", + "monitoruser": "maxuser", + "monitorpw": "maxpwd" + }, + "status": "Master, Running", + "version": "10.1.22-MariaDB", + "node_id": 3000, + "master_id": -1, + "replication_depth": 0, + "slaves": [ + 3001 + ], + "statictics": { + "connections": 0, + "total_connections": 0, + "active_operations": 0 + }, + "relationships": { + "self": "http://localhost:8989/servers/server1", + "services": [ + "http://localhost:8989/services/RW-Split-Router", + "http://localhost:8989/services/Read-Connection-Router" + ], + "monitors": [ + "http://localhost:8989/monitors/MySQL-Monitor" + ] } } ``` @@ -39,7 +58,7 @@ Status: 200 OK #### Supported Request Parameter -- `fields` +- `pretty` ### Get all servers @@ -54,30 +73,65 @@ Status: 200 OK [ { - "name": "db-serv-1", - "address": "192.168.121.58", - "port": 3306, - "protocol": "MySQLBackend", - "status": [ - "master", - "running" - ], + "name": "server1", "parameters": { - "report_weight": 10, - "app_weight": 2 + "address": "127.0.0.1", + "port": 3000, + "protocol": "MySQLBackend", + "monitoruser": "maxuser", + "monitorpw": "maxpwd" + }, + "status": "Master, Running", + "version": "10.1.22-MariaDB", + "node_id": 3000, + "master_id": -1, + "replication_depth": 0, + "slaves": [ + 3001 + ], + "statictics": { + "connections": 0, + "total_connections": 0, + "active_operations": 0 + }, + "relationships": { + "self": "http://localhost:8989/servers/server1", + "services": [ + "http://localhost:8989/services/RW-Split-Router", + "http://localhost:8989/services/Read-Connection-Router" + ], + "monitors": [ + "http://localhost:8989/monitors/MySQL-Monitor" + ] } }, { - "name": "db-serv-2", - "address": "192.168.121.175", - "port": 3306, - "status": [ - "slave", - "running" - ], - "protocol": "MySQLBackend", + "name": "server2", "parameters": { - "app_weight": 6 + "address": "127.0.0.1", + "port": 3001, + "protocol": "MySQLBackend", + "my-weighting-parameter": "3" + }, + "status": "Slave, Running", + "version": "10.1.22-MariaDB", + "node_id": 3001, + "master_id": 3000, + "replication_depth": 1, + "slaves": [], + "statictics": { + "connections": 0, + "total_connections": 0, + "active_operations": 0 + }, + "relationships": { + "self": "http://localhost:8989/servers/server2", + "services": [ + "http://localhost:8989/services/RW-Split-Router" + ], + "monitors": [ + "http://localhost:8989/monitors/MySQL-Monitor" + ] } } ] @@ -85,38 +139,80 @@ Status: 200 OK #### Supported Request Parameter -- `fields` -- `range` +- `pretty` ### Update a server -**Note**: The update mechanisms described here are provisional and most likely - will change in the future. This description is only for design purposes and - does not yet work. - -Partially update a server. The _:name_ in the URI must map to a server name with -all whitespace replaced with hyphens and the request body must be a valid JSON -Patch document which is applied to the resource. +The _:name_ in the URI must map to a server name with all whitespace replaced +with hyphens and the request body must be a valid JSON document representing the +modified server. If the server in question is not found, a 404 Not Found +response is returned. ``` -PATCH /servers/:name +PUT /servers/:name ``` ### Modifiable Fields -|Field |Type |Description | -|-----------|------------|-----------------------------------------------------------------------------| -|address |string |Server address | -|port |number |Server port | -|parameters |object |Server extra parameters | -|state |string array|Server state, array of `master`, `slave`, `synced`, `running` or `maintenance`. An empty array is interpreted as a server that is down.| +The following standard server parameter can be modified. + +- [address](../Getting-Started/Configuration-Guide.md#address) +- [port](../Getting-Started/Configuration-Guide.md#port) +- [monitoruser](../Getting-Started/Configuration-Guide.md#monitoruser) +- [monitorpw](../Getting-Started/Configuration-Guide.md#monitorpw) + +Refer to the documentation on these parameters for valid values. + +The server weighting parameters can also be added, removed and updated. To +remove a parameter, define the value of that parameter as the _null_ JSON type +e.g. `{ "my-param": null }`. To add a parameter, add a new key-value pair to +the _parameters_ object with a name that does not conflict with the standard +parameters. To modify a weighting parameter, simply change the value. + +In addition to standard parameters, the _services_ and _monitors_ fields of the +_relationships_ object can be modified. Removal, addition and modification of +the links will change which service and monitors use this server. + +For example, removing the first value in the _services_ list in the +_relationships_ object from the following JSON document will remove the +_server1_ from the service _RW-Split-Router_. + +Removing a service from a server is analogous to removing the server from the +service. Both unlink the two objects from each other. ``` { - { "op": "replace", "path": "/address", "value": "192.168.0.100" }, - { "op": "replace", "path": "/port", "value": 4006 }, - { "op": "add", "path": "/state/0", "value": "maintenance" }, - { "op": "replace", "path": "/parameters/report_weight", "value": 1 } + "name": "server1", + "parameters": { + "address": "127.0.0.1", + "port": 3000, + "protocol": "MySQLBackend", + "monitoruser": "maxuser", + "monitorpw": "maxpwd" + }, + "status": "Master, Running", + "version": "10.1.22-MariaDB", + "node_id": 3000, + "master_id": -1, + "replication_depth": 0, + "slaves": [ + 3001 + ], + "statictics": { + "connections": 0, + "total_connections": 0, + "active_operations": 0 + }, + "relationships": { + "self": "http://localhost:8989/servers/server1", + "services": [ + "http://localhost:8989/services/RW-Split-Router", // This value is removed + "http://localhost:8989/services/Read-Connection-Router" + ], + "monitors": [ + "http://localhost:8989/monitors/MySQL-Monitor" + ] + } } ``` @@ -128,21 +224,45 @@ Response contains the modified resource. Status: 200 OK { - "name": "db-serv-1", - "protocol": "MySQLBackend", - "address": "192.168.0.100", - "port": 4006, - "state": [ - "maintenance", - "running" - ], + "name": "server1", "parameters": { - "report_weight": 1, - "app_weight": 2 + "address": "127.0.0.1", + "port": 3000, + "protocol": "MySQLBackend", + "monitoruser": "maxuser", + "monitorpw": "maxpwd" + }, + "status": "Master, Running", + "version": "10.1.22-MariaDB", + "node_id": 3000, + "master_id": -1, + "replication_depth": 0, + "slaves": [ + 3001 + ], + "statictics": { + "connections": 0, + "total_connections": 0, + "active_operations": 0 + }, + "relationships": { + "self": "http://localhost:8989/servers/server1", + "services": [ + "http://localhost:8989/services/Read-Connection-Router" + ], + "monitors": [ + "http://localhost:8989/monitors/MySQL-Monitor" + ] } } ``` +#### Supported Request Parameter + +- `pretty` + +# **TODO:** Implement the following features + ### Get all connections to a server Get all connections that are connected to a server.