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

MXS-1220: Update service resource documentation

Browse Source 
Updated service resource documentation. Fixed a few minor typos also in
the server resource documentation.
This commit is contained in:
Markus Mäkelä
2017-05-22 13:12:41 +03:00
parent 9ccb54c107
commit 830e47bc8b
2 changed files with 232 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -330,7 +330,7 @@ response is returned.
### Modifiable Fields ### Modifiable Fields
The following standard server parameter can be modified. The following standard server parameters can be modified.
- [address](../Getting-Started/Configuration-Guide.md#address) - [address](../Getting-Started/Configuration-Guide.md#address)
- [port](../Getting-Started/Configuration-Guide.md#port) - [port](../Getting-Started/Configuration-Guide.md#port)

405
Documentation/REST-API/Resources-Service.md
View File

@ -11,94 +11,226 @@ 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. all whitespace replaced with hyphens. The service names are case-insensitive.
``` ```
GET /services/:name GET /v1/services/:name
``` ```
#### Response #### Response
``` `Status: 200 OK`
Status: 200 OK
```javascript
{ {
"name": "My Service", "links": {
"router": "readwritesplit", "self": "http://localhost:8989/v1/services/Read-Connection-Router"
"router_options": {
"disable_sescmd_history": "true"
}, },
"state": "started", "data": {
"total_connections": 10, "id": "Read-Connection-Router",
"current_connections": 2, "type": "services",
"started": "2016-08-29T12:52:31+03:00", "attributes": {
"filters": [ "router": "readconnroute",
"/filters/Query-Logging-Filter" "state": "Started",
], "router_diagnostics": {
"servers": [ "connections": 0,
"/servers/db-serv-1", "current_connections": 1,
"/servers/db-serv-2", "queries": 0
"/servers/db-serv-3" },
"started": "Mon May 22 12:54:05 2017",
"total_connections": 1,
"connections": 1,
"parameters": { // Service parameters
"router_options": "master",
"user": "maxuser",
"password": "maxpwd",
"enable_root_user": false,
"max_retry_interval": 3600,
"max_connections": 0,
"connection_timeout": 0,
"auth_all_servers": false,
"strip_db_esc": true,
"localhost_match_wildcard_host": true,
"version_string": "",
"log_auth_warnings": true,
"retry_on_failure": true
},
"listeners": [ // Listeners that point to this service
{
"attributes": {
"parameters": {
"port": 4008,
"protocol": "MySQLClient",
"authenticator": "MySQLAuth"
}
},
"id": "Read-Connection-Listener",
"type": "listeners"
}
] ]
},
"relationships": {
"servers": {
"links": {
"self": "http://localhost:8989/v1/servers/"
},
"data": [ // List of servers that this service uses
{
"id": "server1",
"type": "servers"
}
]
}
},
"links": {
"self": "http://localhost:8989/v1/services/Read-Connection-Router"
}
}
} }
``` ```
#### Supported Request Parameter #### Supported Request Parameter
- `fields` - `pretty`
### Get all services ### Get all services
Get all services. Get all services.
``` ```
GET /services GET /v1/services
``` ```
#### Response #### Response
``` `Status: 200 OK`
Status: 200 OK
[ ```javascript
{ {
"name": "My Service", "links": {
"router": "readwritesplit", "self": "http://localhost:8989/v1/services/"
"router_options": {
"disable_sescmd_history": "true"
},
"state": "started",
"total_connections": 10,
"current_connections": 2,
"started": "2016-08-29T12:52:31+03:00",
"filters": [
"/filters/Query-Logging-Filter"
],
"servers": [
"/servers/db-serv-1",
"/servers/db-serv-2",
"/servers/db-serv-3"
]
}, },
"data": [ // Collection of service resources
{ {
"name": "My Second Service", "id": "Read-Connection-Router",
"type": "services",
"attributes": {
"router": "readconnroute", "router": "readconnroute",
"router_options": { "state": "Started",
"type": "master" "router_diagnostics": {
"connections": 0,
"current_connections": 1,
"queries": 0
}, },
"state": "started", "started": "Mon May 22 13:00:46 2017",
"total_connections": 10, "total_connections": 1,
"current_connections": 2, "connections": 1,
"started": "2016-08-29T12:52:31+03:00", "parameters": {
"servers": [ "router_options": "master",
"/servers/db-serv-1", "user": "maxuser",
"/servers/db-serv-2" "password": "maxpwd",
] "enable_root_user": false,
"max_retry_interval": 3600,
"max_connections": 0,
"connection_timeout": 0,
"auth_all_servers": false,
"strip_db_esc": true,
"localhost_match_wildcard_host": true,
"version_string": "",
"log_auth_warnings": true,
"retry_on_failure": true
},
"listeners": [
{
"attributes": {
"parameters": {
"port": 4008,
"protocol": "MySQLClient",
"authenticator": "MySQLAuth"
}
},
"id": "Read-Connection-Listener",
"type": "listeners"
} }
] ]
},
"relationships": {
"servers": {
"links": {
"self": "http://localhost:8989/v1/servers/"
},
"data": [
{
"id": "server1",
"type": "servers"
}
]
}
},
"links": {
"self": "http://localhost:8989/v1/services/Read-Connection-Router"
}
},
{
"id": "CLI",
"type": "services",
"attributes": {
"router": "cli",
"state": "Started",
"started": "Mon May 22 13:00:46 2017",
"total_connections": 2,
"connections": 2,
"parameters": {
"router_options": "",
"user": "",
"password": "",
"enable_root_user": false,
"max_retry_interval": 3600,
"max_connections": 0,
"connection_timeout": 0,
"auth_all_servers": false,
"strip_db_esc": true,
"localhost_match_wildcard_host": true,
"version_string": "",
"log_auth_warnings": true,
"retry_on_failure": true
},
"listeners": [
{
"attributes": {
"parameters": {
"address": "default",
"port": 0,
"protocol": "maxscaled",
"authenticator": "MaxAdminAuth"
}
},
"id": "CLI-Listener",
"type": "listeners"
},
{
"attributes": {
"parameters": {
"address": "0.0.0.0",
"port": 6603,
"protocol": "maxscaled",
"authenticator": "MaxAdminAuth"
}
},
"id": "CLI-Network-Listener",
"type": "listeners"
}
]
},
"relationships": {},
"links": {
"self": "http://localhost:8989/v1/services/CLI"
}
}
]
}
``` ```
#### Supported Request Parameter #### Supported Request Parameter
- `fields` - `pretty`
- `range`
### Get service listeners ### Get service listeners
@ -107,165 +239,68 @@ name with all whitespace replaced with hyphens. The service names are
case-insensitive. case-insensitive.
``` ```
GET /services/:name/listeners GET /v1/services/:name/listeners
``` ```
#### Response #### Response
``` `Status: 200 OK`
Status: 200 OK
[ ```javascript
{ {
"name": "My Listener", "links": {
"protocol": "MySQLClient", "self": "http://localhost:8989/v1/services/Read-Connection-Router/listeners"
"address": "0.0.0.0",
"port": 4006
}, },
"data": [
{ {
"name": "My SSL Listener", "attributes": {
"parameters": {
"port": 4008,
"protocol": "MySQLClient", "protocol": "MySQLClient",
"address": "127.0.0.1", "authenticator": "MySQLAuth"
"port": 4006, }
"ssl": "required", },
"ssl_cert": "/home/markusjm/newcerts/server-cert.pem", "id": "Read-Connection-Listener",
"ssl_key": "/home/markusjm/newcerts/server-key.pem", "type": "listeners"
"ssl_ca_cert": "/home/markusjm/newcerts/ca.pem"
} }
] ]
}
``` ```
#### Supported Request Parameter #### Supported Request Parameter
- `fields` - `pretty`
- `range`
### Update a service ### Update a service
**Note**: The update mechanisms described here are provisional and most likely The _:name_ in the URI must map to a service name and the request body must be a
will change in the future. This description is only for design purposes and valid JSON Patch document which is applied to the resource.
does not yet work.
Partially 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 /services/:name PUT /v1/services/:name
``` ```
### Modifiable Fields The following standard service parameters can be modified.
|Field |Type |Description | - [user](../Getting-Started/Configuration-Guide.md#user)
|--------------|------------|---------------------------------------------------| - [password](../Getting-Started/Configuration-Guide.md#password)
|servers |string array|Servers used by this service, must be relative links to existing server resources| - [enable_root_user](../Getting-Started/Configuration-Guide.md#enable_root_user)
|router_options|object |Router specific options| - [max_retry_interval](../Getting-Started/Configuration-Guide.md#max_retry_interval)
|filters |string array|Service filters, configured in the same order they are declared in the array (`filters[0]` => first filter, `filters[1]` => second filter)| - [max_connections](../Getting-Started/Configuration-Guide.md#max_connections)
|user |string |The username for the service user| - [connection_timeout](../Getting-Started/Configuration-Guide.md#connection_timeout)
|password |string |The password for the service user| - [auth_all_servers](../Getting-Started/Configuration-Guide.md#auth_all_servers)
|root_user |boolean |Allow root user to connect via this service| - [strip_db_esc](../Getting-Started/Configuration-Guide.md#strip_db_esc)
|version_string|string |Custom version string given to connecting clients| - [localhost_match_wildcard_host](../Getting-Started/Configuration-Guide.md#localhost_match_wildcard_host)
|weightby |string |Name of a server weigting parameter which is used for connection weighting| - [version_string](../Getting-Started/Configuration-Guide.md#version_string)
|connection_timeout|number |Client idle timeout in seconds| - [weightby](../Getting-Started/Configuration-Guide.md#weightby)
|max_connection|number |Maximum number of allowed connections| - [log_auth_warnings](../Getting-Started/Configuration-Guide.md#log_auth_warnings)
|strip_db_esc|boolean |Strip escape characters from default database name| - [retry_on_failure](../Getting-Started/Configuration-Guide.md#retry_on_failure)
``` Refer to the documentation on these parameters for valid values.
[
{ "op": "replace", "path": "/servers", "value": ["/servers/db-serv-2","/servers/db-serv-3"] },
{ "op": "add", "path": "/router_options/master_failover_mode", "value": "fail_on_write" },
{ "op": "remove", "path": "/filters" }
]
```
#### Response #### Response
Response contains the modified resource. Service is modified.
```
Status: 200 OK
{
"name": "My Service",
"router": "readwritesplit",
"router_options": {
"disable_sescmd_history=false",
"master_failover_mode": "fail_on_write"
}
"state": "started",
"total_connections": 10,
"current_connections": 2,
"started": "2016-08-29T12:52:31+03:00",
"servers": [
"/servers/db-serv-2",
"/servers/db-serv-3"
]
}
```
### Stop a service
Stops a started service.
```
PUT /service/:name/stop
```
#### Response
```
Status: 204 No Content
```
### Start a service
Starts a stopped service.
```
PUT /service/:name/start
```
#### Response
```
Status: 204 No Content
```
### Get all sessions for a service
Get all sessions for a particular service.
```
GET /services/:name/sessions
```
#### Response
Relative links to all sessions for this service.
```
Status: 200 OK
[
"/sessions/1",
"/sessions/2"
]
```
#### Supported Request Parameter
- `range`
### Close all sessions for a service
Close all sessions for a particular service. This will forcefully close all
client connections and any backend connections they have made.
```
DELETE /services/:name/sessions
```
#### Response
``` ```
Status: 204 No Content Status: 204 No Content