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

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 /servers/:name
GET /v1/servers/:name
```
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
```
```javascript
{
"name": "server1",
"parameters": {
"address": "127.0.0.1",
"port": 3000,
"protocol": "MySQLBackend",
"monitoruser": "maxuser",
"monitorpw": "maxpwd"
"links": {
"self": "http://localhost:8989/v1/servers/server1"
},
"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": {
"id": "server1", // Resource identifier
"type": "servers", // Resource type
"relationships": { // Resource relationships to other resources
"services": { // Services that use this server
"links": {
"self": "http://localhost:8989/v1/services/"
},
"data": [ // References to service resources
{
"id": "RW-Split-Router",
"type": "services"
},
{
"id": "Read-Connection-Router",
"type": "services"
}
]
},
"monitors": { // The monitor that is monitoring this server
"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 /servers
GET /v1/servers
```
#### Response
Response contains an array of all servers.
Response contains a resource collection with all servers.
```
Status: 200 OK
```
[
{
"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",
"http://localhost:8989/services/Read-Connection-Router"
],
"monitors": [
"http://localhost:8989/monitors/MySQL-Monitor"
]
}
```javascript
{
"links": {
"self": "http://localhost:8989/v1/servers/"
},
{
"name": "server2",
"parameters": {
"address": "127.0.0.1",
"port": 3001,
"protocol": "MySQLBackend",
"my-weighting-parameter": "3"
"data": [ // List of server resouces
{
"id": "server1",
"type": "servers",
"relationships": {
"services": {
"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",
"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"
]
{
"id": "server2",
"type": "servers",
"relationships": {
"services": {
"links": {
"self": "http://localhost:8989/v1/services/"
},
"data": [
{
"id": "RW-Split-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": 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
@ -152,7 +230,7 @@ Status: 200 OK
### Create a server
```
POST /servers
POST /v1/servers
```
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
is the minimal required JSON object for defining a new server.
```
```javascript
{
"name": "test-server",
"parameters": {
"address": "127.0.0.1",
"port": 3003
"data": {
"id": "server3",
"type": "servers",
"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 contains the created resource.
Server created:
```
Status: 200 OK
{
"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"
}
}
Status: 204 No Content
```
Invalid JSON body:
```
Status: 400 Bad Request
Status: 403 Forbidden
```
#### Supported Request Parameter
- `pretty`
### 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
@ -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
service. Both unlink the two objects from each other.
```
Response to `GET /v1/server/server1`:
```javascript
{
"name": "server1",
"parameters": {
"address": "127.0.0.1",
"port": 3000,
"protocol": "MySQLBackend",
"monitoruser": "maxuser",
"monitorpw": "maxpwd"
"links": {
"self": "http://localhost:8989/v1/servers/server1"
},
"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"
]
"data": {
"id": "server1",
"type": "servers",
"relationships": {
"services": {
"links": {
"self": "http://localhost:8989/v1/services/"
},
"data": [
{
"id": "RW-Split-Router", // We'll remove this service
"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,
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 contains the modified resource.
Server modified:
```
Status: 200 OK
{
"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"
]
}
}
Status: 204 No Content
```
Server not found:
@ -335,7 +475,7 @@ Status: 404 Not Found
Invalid JSON body:
```
Status: 400 Bad Request
Status: 403 Forbidden
```
#### Supported Request Parameter
@ -345,14 +485,13 @@ Status: 400 Bad Request
### 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
with hyphens.
A server can only be deleted if the only relations in the _relationships_ object
is the _self_ link.
A server can only be deleted if it is not used by any services or monitors.
#### Response
@ -371,7 +510,7 @@ Status: 404 Not Found
Server is in use:
```
Status: 400 Bad Request
Status: 403 Forbidden
```
# **TODO:** Implement the following features
@ -381,56 +520,20 @@ Status: 400 Bad Request
Get all connections that are connected to a server.
```
GET /servers/:name/connections
GET /v1/servers/:name/connections
```
#### 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
- `fields`
- `range`
### Close all connections to a server
Close all connections to a particular server. This will forcefully close all
backend connections.
```
DELETE /servers/:name/connections
DELETE /v1/servers/:name/connections
```
#### Response