59e615eb3c
The Resources document lists all currently known resources and will be converted to a list of separate resource documents once the individual resource documents are done. The Headers and Response Codes document contains a list of request and response headers and the HTTP return codes. This is a work in progress and will be expanded upon. Added initial versions of the filter, monitor, session and user resource documents. These provide information about various parts of MaxScale and allow interaction. All PATCH operations expect a JSON Patch type document in the request body. Examples modified accordingly. Add MaxScale resource document which describes the resources that give the global configuration options and show statistics. The resources that link to other resources provide values as a list of relative links. This reduces the amount of sent data when the client doesn't require all parts of the resource. Since the updating is not yet implement, it should be stated that the update API will most likely be modified at some point. The module resource is similar to `maxadmin show modules` and the log resource contains status information about logs. The log resource also has an "action" resource at `/maxscale/logs/flush` which flushes logs to disk and rotates them. Added start and stop entry points for services and monitors. Also added missing service parameters to the list of parameters that can be updated. The documentation lists listeners as a sub-resource of the service. This allows the listeners of a particular service to be queried.
273 lines
5.8 KiB
Markdown
273 lines
5.8 KiB
Markdown
# Service Resource
|
|
|
|
A service resource represents a service inside MaxScale. A service is a
|
|
collection of network listeners, filters, a router and a set of backend servers.
|
|
|
|
## Resource Operations
|
|
|
|
### 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 /services/:name
|
|
```
|
|
|
|
#### Response
|
|
|
|
```
|
|
Status: 200 OK
|
|
|
|
{
|
|
"name": "My Service",
|
|
"router": "readwritesplit",
|
|
"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"
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Supported Request Parameter
|
|
|
|
- `fields`
|
|
|
|
### Get all services
|
|
|
|
Get all services.
|
|
|
|
```
|
|
GET /services
|
|
```
|
|
|
|
#### Response
|
|
|
|
```
|
|
Status: 200 OK
|
|
|
|
[
|
|
{
|
|
"name": "My Service",
|
|
"router": "readwritesplit",
|
|
"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"
|
|
]
|
|
},
|
|
{
|
|
"name": "My Second Service",
|
|
"router": "readconnroute",
|
|
"router_options": {
|
|
"type": "master"
|
|
},
|
|
"state": "started",
|
|
"total_connections": 10,
|
|
"current_connections": 2,
|
|
"started": "2016-08-29T12:52:31+03:00",
|
|
"servers": [
|
|
"/servers/db-serv-1",
|
|
"/servers/db-serv-2"
|
|
]
|
|
}
|
|
]
|
|
```
|
|
|
|
#### Supported Request Parameter
|
|
|
|
- `fields`
|
|
- `range`
|
|
|
|
### Get service listeners
|
|
|
|
Get the listeners of a 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 /services/:name/listeners
|
|
```
|
|
|
|
#### Response
|
|
|
|
```
|
|
Status: 200 OK
|
|
|
|
[
|
|
{
|
|
"name": "My Listener",
|
|
"protocol": "MySQLClient",
|
|
"address": "0.0.0.0",
|
|
"port": 4006
|
|
},
|
|
{
|
|
"name": "My SSL Listener",
|
|
"protocol": "MySQLClient",
|
|
"address": "127.0.0.1",
|
|
"port": 4006,
|
|
"ssl": "required",
|
|
"ssl_cert": "/home/markusjm/newcerts/server-cert.pem",
|
|
"ssl_key": "/home/markusjm/newcerts/server-key.pem",
|
|
"ssl_ca_cert": "/home/markusjm/newcerts/ca.pem"
|
|
}
|
|
]
|
|
```
|
|
|
|
#### Supported Request Parameter
|
|
|
|
- `fields`
|
|
- `range`
|
|
|
|
### Update a service
|
|
|
|
**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 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
|
|
```
|
|
|
|
### Modifiable Fields
|
|
|
|
|Field |Type |Description |
|
|
|--------------|------------|---------------------------------------------------|
|
|
|servers |string array|Servers used by this service, must be relative links to existing server resources|
|
|
|router_options|object |Router specific options|
|
|
|filters |string array|Service filters, configured in the same order they are declared in the array (`filters[0]` => first filter, `filters[1]` => second filter)|
|
|
|user |string |The username for the service user|
|
|
|password |string |The password for the service user|
|
|
|root_user |boolean |Allow root user to connect via this service|
|
|
|version_string|string |Custom version string given to connecting clients|
|
|
|weightby |string |Name of a server weigting parameter which is used for connection weighting|
|
|
|connection_timeout|number |Client idle timeout in seconds|
|
|
|max_connection|number |Maximum number of allowed connections|
|
|
|strip_db_esc|boolean |Strip escape characters from default database name|
|
|
|
|
```
|
|
[
|
|
{ "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 contains the modified resource.
|
|
|
|
```
|
|
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
|
|
```
|