hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MXS-1220: Update server resource documentation

Browse Source 
Updated documentation with latest resource layouts. Expanded explanations
on how to modify the servers. Use the correct resource endpoints.
This commit is contained in:
Markus Mäkelä
2017-05-11 13:23:41 +03:00
committed by Markus Mäkelä
parent ffc6dba720
commit b317f66335
3 changed files with 429 additions and 365 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
Documentation/Getting-Started/Configuration-Guide.md
View File

@ -1047,6 +1047,18 @@ refuse these due to the lack of the header. To bypass this restriction, the
server monitor needs to be disabled and the service listener needs to be server monitor needs to be disabled and the service listener needs to be
configured to disregard authentication errors (`skip_authentication=true`). configured to disregard authentication errors (`skip_authentication=true`).
#### `authenticator`
The authenticator module to use. Each protocol module defines a default
authentication module which is used if no `authenticator` parameter is found
from the configuration.
#### `authenticator_options`
Option string given to the authenticator module. The value of this parameter
should be a comma-separated list of key-value pairs. See authenticator specific
documentation for more details.
### Server and SSL ### Server and SSL
This section describes configuration parameters for servers that control the This section describes configuration parameters for servers that control the

205
Documentation/REST-API/API.md
View File

@ -4,6 +4,8 @@ This document describes the version 1 of the MaxScale REST API.
## Table of Contents ## Table of Contents
- [Resources](#resources)
- [Common Request Parameter](#common-request-parameters)
- [HTTP Headers](#http-headers) - [HTTP Headers](#http-headers)
- [Request Headers](#request-headers) - [Request Headers](#request-headers)
- [Response Headers](#response-headers) - [Response Headers](#response-headers)
@ -12,8 +14,6 @@ This document describes the version 1 of the MaxScale REST API.
- [3xx Redirection](#3xx-redirection) - [3xx Redirection](#3xx-redirection)
- [4xx Client Error](#4xx-client-error) - [4xx Client Error](#4xx-client-error)
- [5xx Server Error](#5xx-server-error) - [5xx Server Error](#5xx-server-error)
- [Resources](#resources)
- [Common Request Parameter](#common-request-parameters)
## Note About Syntax ## Note About Syntax
@ -21,6 +21,78 @@ 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 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. of the comment and extend to the end of the current line.
## Resources
The MaxScale REST API provides the following resources. All resources conform to
the [JSON API](http://jsonapi.org/format/) specification.
- [/maxscale](Resources-MaxScale.md)
- [/services](Resources-Service.md)
- [/servers](Resources-Server.md)
- [/filters](Resources-Filter.md)
- [/monitors](Resources-Monitor.md)
- [/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 response 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.
## HTTP Headers ## HTTP Headers
### Request Headers ### Request Headers
@ -41,19 +113,9 @@ Credentials for authentication.
All PUT and POST requests must use the `Content-Type: application/json` media All PUT and POST requests must use the `Content-Type: application/json` media
type and the request body must be a valid JSON representation of a resource. All type and the request body must be a valid JSON representation of a resource. All
PATCH requests must use the `Content-Type: application/json-patch` media type PATCH requests must use the `Content-Type: application/json` media type and the
and the request body must be a valid JSON Patch document which is applied to the request body must be a JSON document containing a partial definition of the
resource. Curently, only _add_, _remove_, _replace_ and _test_ operations are original resource.
supported.
Read the [JSON Patch](https://tools.ietf.org/html/draft-ietf-appsawg-json-patch-08)
draft for more details on how to use it with PATCH.
#### Date
This header is required and should be in the RFC 1123 standard form, e.g. Mon,
18 Nov 2013 08:14:29 -0600. Please note that the date must be in English. It
will be checked by the API for being close to the current date and time.
#### Host #### Host
@ -101,8 +163,6 @@ the intended method in the `X-HTTP-Method-Override` header, a client can perform
a POST, PATCH or DELETE request with the PUT method a POST, PATCH or DELETE request with the PUT method
(e.g. `X-HTTP-Method-Override: PATCH`). (e.g. `X-HTTP-Method-Override: PATCH`).
_TODO: Add API version header?_
### Response Headers ### Response Headers
#### Allow #### Allow
@ -294,21 +354,6 @@ contains a more detailed version of the error message.
The server failed to fulfill an apparently valid request. The server failed to fulfill an apparently valid request.
Response status codes beginning with the digit "5" indicate cases in which the
server is aware that it has encountered an error or is otherwise incapable of
performing the request. Except when responding to a HEAD request, the server
includes an entity containing an explanation of the error situation.
```
{
"error": "Log rotation failed",
"description": "Failed to rotate log files: 13, Permission denied"
}
```
The _error_ field contains a short error description and the _description_ field
contains a more detailed version of the error message.
- 500 Internal Server Error - 500 Internal Server Error
- A generic error message, given when an unexpected condition was encountered - A generic error message, given when an unexpected condition was encountered
@ -414,99 +459,3 @@ API could return them.
- The user has sent too many requests in a given amount of time. Intended for - The user has sent too many requests in a given amount of time. Intended for
use with rate-limiting schemes. use with rate-limiting schemes.
## Resources
The MaxScale REST API provides the following resources.
- [/maxscale](Resources-MaxScale.md)
- [/services](Resources-Service.md)
- [/servers](Resources-Server.md)
- [/filters](Resources-Filter.md)
- [/monitors](Resources-Monitor.md)
- [/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 response 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.
This allows the returned object to be filtered so that only needed
parts are returned. The value of this parameter is a comma separated
list of fields to return.
For example, the parameter `?fields=id,name` would return object which
would only contain the _id_ and _name_ fields.
- `range`
- Return a subset of the object array.
The value of this parameter is the range of objects to return given as
a inclusive range separated by a hyphen. If the size of the array is
less than the end of the range, only the objects between the requested
start of the range and the actual end of the array are returned. This
means that
For example, the parameter `?range=10-20` would return objects 10
through 20 from the object array if the actual size of the original
array is greater than or equal to 20.

577
Documentation/REST-API/Resources-Server.md
View File

@ -7,7 +7,7 @@ A server resource represents a backend database server.
### Get a server ### Get a server
``` ```
GET /servers/:name GET /v1/servers/:name
``` ```
Get a single server. The _:name_ in the URI must be a valid server name with all Get a single server. The _:name_ in the URI must be a valid server name with all
@ -20,38 +20,67 @@ whitespace replaced with hyphens. The server names are case-insensitive.
``` ```
Status: 200 OK Status: 200 OK
```
```javascript
{ {
"name": "server1", "links": {
"parameters": { "self": "http://localhost:8989/v1/servers/server1"
"address": "127.0.0.1",
"port": 3000,
"protocol": "MySQLBackend",
"monitoruser": "maxuser",
"monitorpw": "maxpwd"
}, },
"status": "Master, Running", "data": {
"version": "10.1.22-MariaDB", "id": "server1", // Resource identifier
"node_id": 3000, "type": "servers", // Resource type
"master_id": -1, "relationships": { // Resource relationships to other resources
"replication_depth": 0, "services": { // Services that use this server
"slaves": [ "links": {
3001 "self": "http://localhost:8989/v1/services/"
], },
"statictics": { "data": [ // References to service resources
"connections": 0, {
"total_connections": 0, "id": "RW-Split-Router",
"active_operations": 0 "type": "services"
}, },
"relationships": { {
"self": "http://localhost:8989/servers/server1", "id": "Read-Connection-Router",
"services": [ "type": "services"
"http://localhost:8989/services/RW-Split-Router", }
"http://localhost:8989/services/Read-Connection-Router" ]
], },
"monitors": [ "monitors": { // The monitor that is monitoring this server
"http://localhost:8989/monitors/MySQL-Monitor" "links": {
] "self": "http://localhost:8989/v1/monitors/"
},
"data": [
{
"id": "MySQL-Monitor",
"type": "monitors"
}
]
}
},
"attributes": { // Resource attributes
"parameters": { // Server parameters
"address": "127.0.0.1",
"port": 3000,
"protocol": "MySQLBackend"
},
"status": "Master, Running", // Server status string
"version_string": "10.1.22-MariaDB", // Server version
"node_id": 3000, // Server node ID i.e. value of @@server_id
"master_id": -1,
"replication_depth": 0,
"slaves": [ // List of slave server IDs
3001
],
"statictics": { // Server statistics
"connections": 0,
"total_connections": 0,
"active_operations": 0
}
},
"links": { // Link to the server itself
"self": "http://localhost:8989/v1/servers/server1"
}
} }
} }
``` ```
@ -69,80 +98,129 @@ Status: 404 Not Found
### Get all servers ### Get all servers
``` ```
GET /servers GET /v1/servers
``` ```
#### Response #### Response
Response contains an array of all servers. Response contains a resource collection with all servers.
``` ```
Status: 200 OK Status: 200 OK
```
[ ```javascript
{ {
"name": "server1", "links": {
"parameters": { "self": "http://localhost:8989/v1/servers/"
"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"
]
}
}, },
{ "data": [ // List of server resouces
"name": "server2", {
"parameters": { "id": "server1",
"address": "127.0.0.1", "type": "servers",
"port": 3001, "relationships": {
"protocol": "MySQLBackend", "services": {
"my-weighting-parameter": "3" "links": {
"self": "http://localhost:8989/v1/services/"
},
"data": [
{
"id": "RW-Split-Router",
"type": "services"
},
{
"id": "Read-Connection-Router",
"type": "services"
}
]
},
"monitors": {
"links": {
"self": "http://localhost:8989/v1/monitors/"
},
"data": [
{
"id": "MySQL-Monitor",
"type": "monitors"
}
]
}
},
"attributes": {
"parameters": {
"address": "127.0.0.1",
"port": 3000,
"protocol": "MySQLBackend"
},
"status": "Master, Running",
"version_string": "10.1.22-MariaDB",
"node_id": 3000,
"master_id": -1,
"replication_depth": 0,
"slaves": [
3001
],
"statictics": {
"connections": 0,
"total_connections": 0,
"active_operations": 0
}
},
"links": {
"self": "http://localhost:8989/v1/servers/server1"
}
}, },
"status": "Slave, Running", {
"version": "10.1.22-MariaDB", "id": "server2",
"node_id": 3001, "type": "servers",
"master_id": 3000, "relationships": {
"replication_depth": 1, "services": {
"slaves": [], "links": {
"statictics": { "self": "http://localhost:8989/v1/services/"
"connections": 0, },
"total_connections": 0, "data": [
"active_operations": 0 {
}, "id": "RW-Split-Router",
"relationships": { "type": "services"
"self": "http://localhost:8989/servers/server2", }
"services": [ ]
"http://localhost:8989/services/RW-Split-Router" },
], "monitors": {
"monitors": [ "links": {
"http://localhost:8989/monitors/MySQL-Monitor" "self": "http://localhost:8989/v1/monitors/"
] },
"data": [
{
"id": "MySQL-Monitor",
"type": "monitors"
}
]
}
},
"attributes": {
"parameters": {
"address": "127.0.0.1",
"port": 3001,
"protocol": "MySQLBackend"
},
"status": "Slave, Running",
"version_string": "10.1.22-MariaDB",
"node_id": 3001,
"master_id": 3000,
"replication_depth": 1,
"slaves": [],
"statictics": {
"connections": 0,
"total_connections": 0,
"active_operations": 0
}
},
"links": {
"self": "http://localhost:8989/v1/servers/server2"
}
} }
} ]
] }
``` ```
#### Supported Request Parameter #### Supported Request Parameter
@ -152,7 +230,7 @@ Status: 200 OK
### Create a server ### Create a server
``` ```
POST /servers POST /v1/servers
``` ```
Create a new server by defining the resource. The posted object must define the Create a new server by defining the resource. The posted object must define the
@ -160,60 +238,89 @@ _name_ field with the name of the server and the _parameters_ field with JSON
object containing values for the _address_ and _port_ parameters. The following object containing values for the _address_ and _port_ parameters. The following
is the minimal required JSON object for defining a new server. is the minimal required JSON object for defining a new server.
``` ```javascript
{ {
"name": "test-server", "data": {
"parameters": { "id": "server3",
"address": "127.0.0.1", "type": "servers",
"port": 3003 "attributes": {
"parameters": {
"address": "127.0.0.1",
"port": 3003,
"protocol": "MySQLBackend"
}
}
} }
} }
``` ```
The relationships of a server can also be defined at creation time. This allows
new servers to be created and immediately taken into use.
```javascript
{
"data": {
"id": "server4",
"type": "servers",
"attributes": {
"parameters": {
"address": "127.0.0.1",
"port": 3002,
"protocol": "MySQLBackend"
}
},
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
},
{
"id": "Read-Connection-Router",
"type": "services"
}
]
},
"monitors": {
"data": [
{
"id": "MySQL-Monitor",
"type": "monitors"
}
]
}
}
}
}
```
The following parameters can be defined when a server is being created.
- [address](../Getting-Started/Configuration-Guide.md#address)
- [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)
#### Response #### Response
Response contains the created resource. Server created:
``` ```
Status: 200 OK Status: 204 No Content
{
"name": "test-server",
"parameters": {
"address": "127.0.0.1",
"port": 3003,
"protocol": "MySQLBackend"
},
"status": "Running",
"node_id": -1,
"master_id": -1,
"replication_depth": -1,
"slaves": [],
"statictics": {
"connections": 0,
"total_connections": 0,
"active_operations": 0
},
"relationships": {
"self": "http://localhost:8989/servers/test-server"
}
}
``` ```
Invalid JSON body: Invalid JSON body:
``` ```
Status: 400 Bad Request Status: 403 Forbidden
``` ```
#### Supported Request Parameter
- `pretty`
### Update a server ### Update a server
``` ```
PUT /servers/:name PUT /v1/servers/:name
``` ```
The _:name_ in the URI must map to a server name with all whitespace replaced The _:name_ in the URI must map to a server name with all whitespace replaced
@ -249,81 +356,114 @@ _server1_ from the service _RW-Split-Router_.
Removing a service from a server is analogous to removing the server from the Removing a service from a server is analogous to removing the server from the
service. Both unlink the two objects from each other. service. Both unlink the two objects from each other.
``` Response to `GET /v1/server/server1`:
```javascript
{ {
"name": "server1", "links": {
"parameters": { "self": "http://localhost:8989/v1/servers/server1"
"address": "127.0.0.1",
"port": 3000,
"protocol": "MySQLBackend",
"monitoruser": "maxuser",
"monitorpw": "maxpwd"
}, },
"status": "Master, Running", "data": {
"version": "10.1.22-MariaDB", "id": "server1",
"node_id": 3000, "type": "servers",
"master_id": -1, "relationships": {
"replication_depth": 0, "services": {
"slaves": [ "links": {
3001 "self": "http://localhost:8989/v1/services/"
], },
"statictics": { "data": [
"connections": 0, {
"total_connections": 0, "id": "RW-Split-Router", // We'll remove this service
"active_operations": 0 "type": "services"
}, },
"relationships": { {
"self": "http://localhost:8989/servers/server1", "id": "Read-Connection-Router",
"services": [ "type": "services"
"http://localhost:8989/services/RW-Split-Router", // This value is removed }
"http://localhost:8989/services/Read-Connection-Router" ]
], },
"monitors": [ "monitors": {
"http://localhost:8989/monitors/MySQL-Monitor" "links": {
] "self": "http://localhost:8989/v1/monitors/"
},
"data": [
{
"id": "MySQL-Monitor",
"type": "monitors"
}
]
}
},
"attributes": {
"parameters": {
"address": "127.0.0.1",
"port": 3000,
"protocol": "MySQLBackend"
},
"status": "Master, Running",
"version_string": "10.1.22-MariaDB",
"node_id": 3000,
"master_id": -1,
"replication_depth": 0,
"slaves": [
3001,
3002
],
"statictics": {
"connections": 0,
"total_connections": 0,
"active_operations": 0
}
},
"links": {
"self": "http://localhost:8989/v1/servers/server1"
}
} }
} }
``` ```
Request for `PUT /v1/server/server1`:
```javascript
{
"data": {
"id": "server1",
"type": "servers",
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
]
},
"monitors": {
"data": [
{
"id": "MySQL-Monitor",
"type": "monitors"
}
]
}
}
}
}
```
The current implementation accepts both PUT and PATCH requests with partially
defined resources as request body. If parts of the resource are not defined
(e.g. the `attributes` field in the above example), those parts of the resource
are not modified. All parts that are defined are interpreted as the new
definition of those part of the resource. In the above example, the
`relationships` of the resource are completely redefined.
#### Response #### Response
Response contains the modified resource. Server modified:
``` ```
Status: 200 OK Status: 204 No Content
{
"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/Read-Connection-Router"
],
"monitors": [
"http://localhost:8989/monitors/MySQL-Monitor"
]
}
}
``` ```
Server not found: Server not found:
@ -335,7 +475,7 @@ Status: 404 Not Found
Invalid JSON body: Invalid JSON body:
``` ```
Status: 400 Bad Request Status: 403 Forbidden
``` ```
#### Supported Request Parameter #### Supported Request Parameter
@ -345,14 +485,13 @@ Status: 400 Bad Request
### Destroy a server ### Destroy a server
``` ```
DELETE /servers/:name DELETE /v1/servers/:name
``` ```
The _:name_ in the URI must map to a server name with all whitespace replaced The _:name_ in the URI must map to a server name with all whitespace replaced
with hyphens. with hyphens.
A server can only be deleted if the only relations in the _relationships_ object A server can only be deleted if it is not used by any services or monitors.
is the _self_ link.
#### Response #### Response
@ -371,7 +510,7 @@ Status: 404 Not Found
Server is in use: Server is in use:
``` ```
Status: 400 Bad Request Status: 403 Forbidden
``` ```
# **TODO:** Implement the following features # **TODO:** Implement the following features
@ -381,56 +520,20 @@ Status: 400 Bad Request
Get all connections that are connected to a server. Get all connections that are connected to a server.
``` ```
GET /servers/:name/connections GET /v1/servers/:name/connections
``` ```
#### Response #### Response
```
Status: 200 OK
[
{
"state": "DCB in the polling loop",
"role": "Backend Request Handler",
"server": "/servers/db-serv-01",
"service": "/services/my-service",
"statistics": {
"reads": 2197
"writes": 1562
"buffered_writes": 0
"high_water_events": 0
"low_water_events": 0
}
},
{
"state": "DCB in the polling loop",
"role": "Backend Request Handler",
"server": "/servers/db-serv-01",
"service": "/services/my-second-service"
"statistics": {
"reads": 0
"writes": 0
"buffered_writes": 0
"high_water_events": 0
"low_water_events": 0
}
}
]
```
#### Supported Request Parameter #### Supported Request Parameter
- `fields`
- `range`
### Close all connections to a server ### Close all connections to a server
Close all connections to a particular server. This will forcefully close all Close all connections to a particular server. This will forcefully close all
backend connections. backend connections.
``` ```
DELETE /servers/:name/connections DELETE /v1/servers/:name/connections
``` ```
#### Response #### Response