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