diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index dbe271171..976e150f4 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -1047,6 +1047,18 @@ refuse these due to the lack of the header. To bypass this restriction, the server monitor needs to be disabled and the service listener needs to be configured to disregard authentication errors (`skip_authentication=true`). +#### `authenticator` + +The authenticator module to use. Each protocol module defines a default +authentication module which is used if no `authenticator` parameter is found +from the configuration. + +#### `authenticator_options` + +Option string given to the authenticator module. The value of this parameter +should be a comma-separated list of key-value pairs. See authenticator specific +documentation for more details. + ### Server and SSL This section describes configuration parameters for servers that control the diff --git a/Documentation/REST-API/API.md b/Documentation/REST-API/API.md index 1a297126d..2bc7980df 100644 --- a/Documentation/REST-API/API.md +++ b/Documentation/REST-API/API.md @@ -4,6 +4,8 @@ This document describes the version 1 of the MaxScale REST API. ## Table of Contents +- [Resources](#resources) +- [Common Request Parameter](#common-request-parameters) - [HTTP Headers](#http-headers) - [Request Headers](#request-headers) - [Response Headers](#response-headers) @@ -12,8 +14,6 @@ This document describes the version 1 of the MaxScale REST API. - [3xx Redirection](#3xx-redirection) - [4xx Client Error](#4xx-client-error) - [5xx Server Error](#5xx-server-error) -- [Resources](#resources) -- [Common Request Parameter](#common-request-parameters) ## Note About Syntax @@ -21,6 +21,78 @@ Although JSON does not define a syntax for comments, some of the JSON examples have C-style inline comments in them. These comments use `//` to mark the start of the comment and extend to the end of the current line. +## Resources + +The MaxScale REST API provides the following resources. All resources conform to +the [JSON API](http://jsonapi.org/format/) specification. + +- [/maxscale](Resources-MaxScale.md) +- [/services](Resources-Service.md) +- [/servers](Resources-Server.md) +- [/filters](Resources-Filter.md) +- [/monitors](Resources-Monitor.md) +- [/sessions](Resources-Session.md) +- [/users](Resources-User.md) + +### Resource Relationships + +All resources return complete JSON objects. The returned objects can have a +_relationships_ field that represents any relations the object has to other +objects. This closely resembles the JSON API definition of links. + +In the _relationships_ objects, all resources have a _self_ link that points to +the resource itself. This allows for easier updating of resources as the reply +URL is included in the response itself. + +The following lists the resources and the types of links each resource can have +in addition to the _self_ link. + +- `services` - Service resource + + - `servers` + + List of servers used by the service + + - `filters` + + List of filters used by the service + +- `monitors` - Monitor resource + + - `servers` + + List of servers used by the monitor + +- `filters` - Filter resource + + - `services` + + List of services that use this filter + +- `servers` - Server resource + + - `services` + + List of services that use this server + + - `monitors` + + List of monitors that use this server + +## Common Request Parameters + +Most of the resources that support GET also support the following +parameters. See the resource documentation for a list of supported request +parameters. + +- `pretty` + + - Pretty-print output. + + If this parameter is set to `true` then the returned objects are + formatted in a more human readable format. All resources support this + parameter. + ## HTTP Headers ### Request Headers @@ -41,19 +113,9 @@ Credentials for authentication. All PUT and POST requests must use the `Content-Type: application/json` media type and the request body must be a valid JSON representation of a resource. All -PATCH requests must use the `Content-Type: application/json-patch` media type -and the request body must be a valid JSON Patch document which is applied to the -resource. Curently, only _add_, _remove_, _replace_ and _test_ operations are -supported. - -Read the [JSON Patch](https://tools.ietf.org/html/draft-ietf-appsawg-json-patch-08) -draft for more details on how to use it with PATCH. - -#### Date - -This header is required and should be in the RFC 1123 standard form, e.g. Mon, -18 Nov 2013 08:14:29 -0600. Please note that the date must be in English. It -will be checked by the API for being close to the current date and time. +PATCH requests must use the `Content-Type: application/json` media type and the +request body must be a JSON document containing a partial definition of the +original resource. #### Host @@ -101,8 +163,6 @@ the intended method in the `X-HTTP-Method-Override` header, a client can perform a POST, PATCH or DELETE request with the PUT method (e.g. `X-HTTP-Method-Override: PATCH`). -_TODO: Add API version header?_ - ### Response Headers #### Allow @@ -294,21 +354,6 @@ contains a more detailed version of the error message. The server failed to fulfill an apparently valid request. -Response status codes beginning with the digit "5" indicate cases in which the -server is aware that it has encountered an error or is otherwise incapable of -performing the request. Except when responding to a HEAD request, the server -includes an entity containing an explanation of the error situation. - -``` -{ - "error": "Log rotation failed", - "description": "Failed to rotate log files: 13, Permission denied" -} -``` - -The _error_ field contains a short error description and the _description_ field -contains a more detailed version of the error message. - - 500 Internal Server Error - A generic error message, given when an unexpected condition was encountered @@ -414,99 +459,3 @@ API could return them. - The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes. - -## Resources - -The MaxScale REST API provides the following resources. - -- [/maxscale](Resources-MaxScale.md) -- [/services](Resources-Service.md) -- [/servers](Resources-Server.md) -- [/filters](Resources-Filter.md) -- [/monitors](Resources-Monitor.md) -- [/sessions](Resources-Session.md) -- [/users](Resources-User.md) - -### Resource Relationships - -All resources return complete JSON objects. The returned objects can have a -_relationships_ field that represents any relations the object has to other -objects. This closely resembles the JSON API definition of links. - -In the _relationships_ objects, all resources have a _self_ link that points to -the resource itself. This allows for easier updating of resources as the reply -URL is included in the response itself. - -The following lists the resources and the types of links each resource can have -in addition to the _self_ link. - -- `services` - Service resource - - - `servers` - - List of servers used by the service - - - `filters` - - List of filters used by the service - -- `monitors` - Monitor resource - - - `servers` - - List of servers used by the monitor - -- `filters` - Filter resource - - - `services` - - List of services that use this filter - -- `servers` - Server resource - - - `services` - - List of services that use this server - - - `monitors` - - List of monitors that use this server - -## Common Request Parameters - -Most of the resources that support GET also support the following -parameters. See the resource documentation for a list of supported request -parameters. - -- `pretty` - - - Pretty-print output. - - If this parameter is set to `true` then the returned objects are - formatted in a more human readable format. All resources support this - parameter. - -- `fields` - - - A list of fields to return. - - This allows the returned object to be filtered so that only needed - parts are returned. The value of this parameter is a comma separated - list of fields to return. - - For example, the parameter `?fields=id,name` would return object which - would only contain the _id_ and _name_ fields. - -- `range` - - - Return a subset of the object array. - - The value of this parameter is the range of objects to return given as - a inclusive range separated by a hyphen. If the size of the array is - less than the end of the range, only the objects between the requested - start of the range and the actual end of the array are returned. This - means that - - For example, the parameter `?range=10-20` would return objects 10 - through 20 from the object array if the actual size of the original - array is greater than or equal to 20. diff --git a/Documentation/REST-API/Resources-Server.md b/Documentation/REST-API/Resources-Server.md index b2bc34569..9309f0cad 100644 --- a/Documentation/REST-API/Resources-Server.md +++ b/Documentation/REST-API/Resources-Server.md @@ -7,7 +7,7 @@ A server resource represents a backend database server. ### Get a server ``` -GET /servers/:name +GET /v1/servers/:name ``` Get a single server. The _:name_ in the URI must be a valid server name with all @@ -20,38 +20,67 @@ whitespace replaced with hyphens. The server names are case-insensitive. ``` Status: 200 OK +``` +```javascript { - "name": "server1", - "parameters": { - "address": "127.0.0.1", - "port": 3000, - "protocol": "MySQLBackend", - "monitoruser": "maxuser", - "monitorpw": "maxpwd" + "links": { + "self": "http://localhost:8989/v1/servers/server1" }, - "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" - ] + "data": { + "id": "server1", // Resource identifier + "type": "servers", // Resource type + "relationships": { // Resource relationships to other resources + "services": { // Services that use this server + "links": { + "self": "http://localhost:8989/v1/services/" + }, + "data": [ // References to service resources + { + "id": "RW-Split-Router", + "type": "services" + }, + { + "id": "Read-Connection-Router", + "type": "services" + } + ] + }, + "monitors": { // The monitor that is monitoring this server + "links": { + "self": "http://localhost:8989/v1/monitors/" + }, + "data": [ + { + "id": "MySQL-Monitor", + "type": "monitors" + } + ] + } + }, + "attributes": { // Resource attributes + "parameters": { // Server parameters + "address": "127.0.0.1", + "port": 3000, + "protocol": "MySQLBackend" + }, + "status": "Master, Running", // Server status string + "version_string": "10.1.22-MariaDB", // Server version + "node_id": 3000, // Server node ID i.e. value of @@server_id + "master_id": -1, + "replication_depth": 0, + "slaves": [ // List of slave server IDs + 3001 + ], + "statictics": { // Server statistics + "connections": 0, + "total_connections": 0, + "active_operations": 0 + } + }, + "links": { // Link to the server itself + "self": "http://localhost:8989/v1/servers/server1" + } } } ``` @@ -69,80 +98,129 @@ Status: 404 Not Found ### Get all servers ``` -GET /servers +GET /v1/servers ``` #### Response -Response contains an array of all servers. +Response contains a resource collection with 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" - ] - } +```javascript +{ + "links": { + "self": "http://localhost:8989/v1/servers/" }, - { - "name": "server2", - "parameters": { - "address": "127.0.0.1", - "port": 3001, - "protocol": "MySQLBackend", - "my-weighting-parameter": "3" + "data": [ // List of server resouces + { + "id": "server1", + "type": "servers", + "relationships": { + "services": { + "links": { + "self": "http://localhost:8989/v1/services/" + }, + "data": [ + { + "id": "RW-Split-Router", + "type": "services" + }, + { + "id": "Read-Connection-Router", + "type": "services" + } + ] + }, + "monitors": { + "links": { + "self": "http://localhost:8989/v1/monitors/" + }, + "data": [ + { + "id": "MySQL-Monitor", + "type": "monitors" + } + ] + } + }, + "attributes": { + "parameters": { + "address": "127.0.0.1", + "port": 3000, + "protocol": "MySQLBackend" + }, + "status": "Master, Running", + "version_string": "10.1.22-MariaDB", + "node_id": 3000, + "master_id": -1, + "replication_depth": 0, + "slaves": [ + 3001 + ], + "statictics": { + "connections": 0, + "total_connections": 0, + "active_operations": 0 + } + }, + "links": { + "self": "http://localhost:8989/v1/servers/server1" + } }, - "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" - ] + { + "id": "server2", + "type": "servers", + "relationships": { + "services": { + "links": { + "self": "http://localhost:8989/v1/services/" + }, + "data": [ + { + "id": "RW-Split-Router", + "type": "services" + } + ] + }, + "monitors": { + "links": { + "self": "http://localhost:8989/v1/monitors/" + }, + "data": [ + { + "id": "MySQL-Monitor", + "type": "monitors" + } + ] + } + }, + "attributes": { + "parameters": { + "address": "127.0.0.1", + "port": 3001, + "protocol": "MySQLBackend" + }, + "status": "Slave, Running", + "version_string": "10.1.22-MariaDB", + "node_id": 3001, + "master_id": 3000, + "replication_depth": 1, + "slaves": [], + "statictics": { + "connections": 0, + "total_connections": 0, + "active_operations": 0 + } + }, + "links": { + "self": "http://localhost:8989/v1/servers/server2" + } } - } -] + ] +} ``` #### Supported Request Parameter @@ -152,7 +230,7 @@ Status: 200 OK ### Create a server ``` -POST /servers +POST /v1/servers ``` Create a new server by defining the resource. The posted object must define the @@ -160,60 +238,89 @@ _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. -``` +```javascript { - "name": "test-server", - "parameters": { - "address": "127.0.0.1", - "port": 3003 + "data": { + "id": "server3", + "type": "servers", + "attributes": { + "parameters": { + "address": "127.0.0.1", + "port": 3003, + "protocol": "MySQLBackend" + } + } } } ``` +The relationships of a server can also be defined at creation time. This allows +new servers to be created and immediately taken into use. + +```javascript +{ + "data": { + "id": "server4", + "type": "servers", + "attributes": { + "parameters": { + "address": "127.0.0.1", + "port": 3002, + "protocol": "MySQLBackend" + } + }, + "relationships": { + "services": { + "data": [ + { + "id": "RW-Split-Router", + "type": "services" + }, + { + "id": "Read-Connection-Router", + "type": "services" + } + ] + }, + "monitors": { + "data": [ + { + "id": "MySQL-Monitor", + "type": "monitors" + } + ] + } + } + } +} +``` + +The following parameters can be defined when a server is being created. + +- [address](../Getting-Started/Configuration-Guide.md#address) +- [port](../Getting-Started/Configuration-Guide.md#port) +- [protocol](../Getting-Started/Configuration-Guide.md#protocol) +- [authenticator](../Getting-Started/Configuration-Guide.md#authenticator) +- [authenticator_options](../Getting-Started/Configuration-Guide.md#authenticator-options) + #### Response -Response contains the created resource. +Server created: ``` -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" - } -} +Status: 204 No Content ``` Invalid JSON body: ``` -Status: 400 Bad Request +Status: 403 Forbidden ``` -#### Supported Request Parameter - -- `pretty` - ### Update a server ``` -PUT /servers/:name +PUT /v1/servers/:name ``` The _:name_ in the URI must map to a server name with all whitespace replaced @@ -249,81 +356,114 @@ _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. -``` +Response to `GET /v1/server/server1`: + +```javascript { - "name": "server1", - "parameters": { - "address": "127.0.0.1", - "port": 3000, - "protocol": "MySQLBackend", - "monitoruser": "maxuser", - "monitorpw": "maxpwd" + "links": { + "self": "http://localhost:8989/v1/servers/server1" }, - "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" - ] + "data": { + "id": "server1", + "type": "servers", + "relationships": { + "services": { + "links": { + "self": "http://localhost:8989/v1/services/" + }, + "data": [ + { + "id": "RW-Split-Router", // We'll remove this service + "type": "services" + }, + { + "id": "Read-Connection-Router", + "type": "services" + } + ] + }, + "monitors": { + "links": { + "self": "http://localhost:8989/v1/monitors/" + }, + "data": [ + { + "id": "MySQL-Monitor", + "type": "monitors" + } + ] + } + }, + "attributes": { + "parameters": { + "address": "127.0.0.1", + "port": 3000, + "protocol": "MySQLBackend" + }, + "status": "Master, Running", + "version_string": "10.1.22-MariaDB", + "node_id": 3000, + "master_id": -1, + "replication_depth": 0, + "slaves": [ + 3001, + 3002 + ], + "statictics": { + "connections": 0, + "total_connections": 0, + "active_operations": 0 + } + }, + "links": { + "self": "http://localhost:8989/v1/servers/server1" + } } } ``` +Request for `PUT /v1/server/server1`: + +```javascript +{ + "data": { + "id": "server1", + "type": "servers", + "relationships": { + "services": { + "data": [ + { + "id": "Read-Connection-Router", + "type": "services" + } + ] + }, + "monitors": { + "data": [ + { + "id": "MySQL-Monitor", + "type": "monitors" + } + ] + } + } + } +} +``` + +The current implementation accepts both PUT and PATCH requests with partially +defined resources as request body. If parts of the resource are not defined +(e.g. the `attributes` field in the above example), those parts of the resource +are not modified. All parts that are defined are interpreted as the new +definition of those part of the resource. In the above example, the +`relationships` of the resource are completely redefined. + #### Response -Response contains the modified resource. +Server modified: ``` -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" - ] - } -} +Status: 204 No Content ``` Server not found: @@ -335,7 +475,7 @@ Status: 404 Not Found Invalid JSON body: ``` -Status: 400 Bad Request +Status: 403 Forbidden ``` #### Supported Request Parameter @@ -345,14 +485,13 @@ Status: 400 Bad Request ### Destroy a server ``` -DELETE /servers/:name +DELETE /v1/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. +A server can only be deleted if it is not used by any services or monitors. #### Response @@ -371,7 +510,7 @@ Status: 404 Not Found Server is in use: ``` -Status: 400 Bad Request +Status: 403 Forbidden ``` # **TODO:** Implement the following features @@ -381,56 +520,20 @@ Status: 400 Bad Request Get all connections that are connected to a server. ``` -GET /servers/:name/connections +GET /v1/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 +DELETE /v1/servers/:name/connections ``` #### Response