Files
MaxScale/Documentation/REST-API/Resources-Server.md
Markus Mäkelä bcbff5da1b MXS-1220: Add POST and DELETE documentation for servers
Added POST and DELETE documentation on the servers resource. Also cleaned
up formatting.
2017-05-04 09:17:54 +03:00

9.5 KiB

Server Resource

A server resource represents a backend database server.

Resource Operations

Get a server

GET /servers/:name

Get a single server. The :name in the URI must be a valid server name with all whitespace replaced with hyphens. The server names are case-insensitive.

Note: The parameters field contains all custom parameters for servers, including the server weighting parameters.

Response

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"
        ]
    }
}

Server not found:

Status: 404 Not Found

Supported Request Parameter

  • pretty

Get all servers

GET /servers

Response

Response contains an array of 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"
            ]
        }
    },
    {
        "name": "server2",
        "parameters": {
            "address": "127.0.0.1",
            "port": 3001,
            "protocol": "MySQLBackend",
            "my-weighting-parameter": "3"
        },
        "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"
            ]
        }
    }
]

Supported Request Parameter

  • pretty

Create a server

POST /servers

Create a new server by defining the resource. The posted object must define the 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.

{
    "name": "test-server",
    "parameters": {
        "address": "127.0.0.1",
        "port": 3003
    }
}

Response

Response contains the created resource.

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"
    }
}

Invalid JSON body:

Status: 400 Bad Request

Supported Request Parameter

  • pretty

Update a server

PUT /servers/:name

The :name in the URI must map to a server name with all whitespace replaced with hyphens and the request body must be a valid JSON document representing the modified server. If the server in question is not found, a 404 Not Found response is returned.

Modifiable Fields

The following standard server parameter can be modified.

Refer to the documentation on these parameters for valid values.

The server weighting parameters can also be added, removed and updated. To remove a parameter, define the value of that parameter as the null JSON type e.g. { "my-param": null }. To add a parameter, add a new key-value pair to the parameters object with a name that does not conflict with the standard parameters. To modify a weighting parameter, simply change the value.

In addition to standard parameters, the services and monitors fields of the relationships object can be modified. Removal, addition and modification of the links will change which service and monitors use this server.

For example, removing the first value in the services list in the relationships object from the following JSON document will remove the 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.

{
    "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", // This value is removed
            "http://localhost:8989/services/Read-Connection-Router"
        ],
        "monitors": [
            "http://localhost:8989/monitors/MySQL-Monitor"
        ]
    }
}

Response

Response contains the modified resource.

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"
        ]
    }
}

Server not found:

Status: 404 Not Found

Invalid JSON body:

Status: 400 Bad Request

Supported Request Parameter

  • pretty

Destroy a server

DELETE /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.

Response

OK:

Status: 204 No Content

Server not found:

Status: 404 Not Found

Server is in use:

Status: 400 Bad Request

TODO: Implement the following features

Get all connections to a server

Get all connections that are connected to a server.

GET /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

Response

Status: 204 No Content