hcq/MaxScale
hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
MaxScale/Documentation/REST-API/Resources-Service.md
Markus Makela 59e615eb3c Create initial REST API documentation 
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.
2016-11-07 14:20:44 +02:00

5.8 KiB
Raw Blame History

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