diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md index 69070b10b..0b2fe2a43 100644 --- a/Documentation/Documentation-Contents.md +++ b/Documentation/Documentation-Contents.md @@ -31,6 +31,7 @@ - [Debug and Diagnostic Support](Reference/Debug-And-Diagnostic-Support.md) - [Routing Hints](Reference/Hint-Syntax.md) - [MaxBinlogCheck](Reference/MaxBinlogCheck.md) + - [MaxScale REST API](REST-API/API.md) ## Tutorials diff --git a/Documentation/REST-API/API.md b/Documentation/REST-API/API.md new file mode 100644 index 000000000..afa08573b --- /dev/null +++ b/Documentation/REST-API/API.md @@ -0,0 +1,453 @@ +# REST API design document + +This document describes the version 1 of the MaxScale REST API. + +## Table of Contents + +- [HTTP Headers](#http-headers) + - [Request Headers](#request-headers) + - [Response Headers](#response-headers) +- [Response Codes](#response-codes) + - [2xx Success](#2xx-success) + - [3xx Redirection](#3xx-redirection) + - [4xx Client Error](#4xx-client-error) + - [5xx Server Error](#5xx-server-error) +- [Resources](#resources) +- [Common Request Parameter](#common-request-parameters) + +## HTTP Headers + +### Request Headers + +REST makes use of the HTTP protocols in its aim to provide a natural way to +understand the workings of an API. The following request headers are understood +by this API. + +#### Accept-Charset + +Acceptable character sets. + +#### Authorization + +Credentials for authentication. + +#### Content-Type + +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. + +#### Host + +The address and port of the server. + +#### If-Match + +The request is performed only if the provided ETag value matches the one on the +server. This field should be used with PUT requests to prevent concurrent +updates to the same resource. + +The value of this header must be a value from the `ETag` header retrieved from +the same resource at an earlier point in time. + +#### If-Modified-Since + +If the content has not changed the server responds with a 304 status code. If +the content has changed the server responds with a 200 status code and the +requested resource. + +The value of this header must be a date value in the +["HTTP-date"](https://www.ietf.org/rfc/rfc2822.txt) format. + +#### If-None-Match + +If the content has not changed the server responds with a 304 status code. If +the content has changed the server responds with a 200 status code and the +requested resource. + +The value of this header must be a value from the `ETag` header retrieved from +the same resource at an earlier point in time. + +#### If-Unmodified-Since + +The request is performed only if the requested resource has not been modified +since the provided date. + +The value of this header must be a date value in the +["HTTP-date"](https://www.ietf.org/rfc/rfc2822.txt) format. + +#### X-HTTP-Method-Override + +Some clients only support GET and PUT requests. By providing the string value of +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 + +All resources return the Allow header with the supported HTTP methods. For +example the resource `/service` will always return the `Accept: GET, PATCH, PUT` +header. + +#### Accept-Patch + +All PATCH capable resources return the `Accept-Patch: application/json-patch` +header. + +#### Date + +Returns the RFC 1123 standard form date when the reply was sent. The date is in +English and it uses the server's local timezone. + +#### ETag + +An identifier for a specific version of a resource. The value of this header +changes whenever a resource is modified. + +When the client sends the `If-Match` or `If-None-Match` header, the provided +value should be the value of the `ETag` header of an earlier GET. + +#### Last-Modified + +The date when the resource was last modified in "HTTP-date" format. + +#### Location + +If an out of date resource location is requested, a HTTP return code of 3XX with +the `Location` header is returned. The value of the header contains the new +location of the requested resource as a relative URI. + +#### WWW-Authenticate + +The requested authentication method. For example, `WWW-Authenticate: Basic` +would require basic HTTP authentication. + +## Response Codes + +Every HTTP response starts with a line with a return code which indicates the +outcome of the request. The API uses some of the standard HTTP values: + +### 2xx Success + +- 200 OK + + - Successful HTTP requests, response has a body. + +- 201 Created + + - A new resource was created. + +- 202 Accepted + + - The request has been accepted for processing, but the processing has not + been completed. + +- 204 No Content + + - Successful HTTP requests, response has no body. + +### 3xx Redirection + +This class of status code indicates the client must take additional action to +complete the request. + +- 301 Moved Permanently + + - This and all future requests should be directed to the given URI. + +- 302 Found + + - The response to the request can be found under another URI using the same + method as in the original request. + +- 303 See Other + + - The response to the request can be found under another URI using a GET + method. + +- 304 Not Modified + + - Indicates that the resource has not been modified since the version + specified by the request headers If-Modified-Since or If-None-Match. + +- 307 Temporary Redirect + + - The request should be repeated with another URI but future requests should + use the original URI. + +- 308 Permanent Redirect + + - The request and all future requests should be repeated using another URI. + +### 4xx Client Error + +The 4xx class of status code is when the client seems to have erred. Except when +responding to a HEAD request, the body of the response contains a JSON +representation of the error in the following format. + +``` +{ + "error": "Method not supported", + "description": "The `/service` resource does not support POST." +} +``` + +The _error_ field contains a short error description and the _description_ field +contains a more detailed version of the error message. + +- 400 Bad Request + + - The server cannot or will not process the request due to client error. + +- 401 Unauthorized + + - Authentication is required. The response includes a WWW-Authenticate header. + +- 403 Forbidden + + - The request was a valid request, but the client does not have the necessary + permissions for the resource. + +- 404 Not Found + + - The requested resource could not be found. + +- 405 Method Not Allowed + + - A request method is not supported for the requested resource. + +- 406 Not Acceptable + + - The requested resource is capable of generating only content not acceptable + according to the Accept headers sent in the request. + +- 409 Conflict + + - Indicates that the request could not be processed because of conflict in the + request, such as an edit conflict be tween multiple simultaneous updates. + +- 411 Length Required + + - The request did not specify the length of its content, which is required by + the requested resource. + +- 412 Precondition Failed + + - The server does not meet one of the preconditions that the requester put on + the request. + +- 413 Payload Too Large + + - The request is larger than the server is willing or able to process. + +- 414 URI Too Long + + - The URI provided was too long for the server to process. + +- 415 Unsupported Media Type + + - The request entity has a media type which the server or resource does not + support. + +- 422 Unprocessable Entity + + - The request was well-formed but was unable to be followed due to semantic + errors. + +- 423 Locked + + - The resource that is being accessed is locked. + +- 428 Precondition Required + + - The origin server requires the request to be conditional. This error code is + returned when none of the `Modified-Since` or `Match` type headers are used. + +- 431 Request Header Fields Too Large + + - The server is unwilling to process the request because either an individual + header field, or all the header fields collectively, are too large. + +### 5xx Server Error + +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 + and no more specific message is suitable. + +- 501 Not Implemented + + - The server either does not recognize the request method, or it lacks the + ability to fulfill the request. + +- 502 Bad Gateway + + - The server was acting as a gateway or proxy and received an invalid response + from the upstream server. + +- 503 Service Unavailable + + - The server is currently unavailable (because it is overloaded or down for + maintenance). Generally, this is a temporary state. + +- 504 Gateway Timeout + + - The server was acting as a gateway or proxy and did not receive a timely + response from the upstream server. + +- 505 HTTP Version Not Supported + + - The server does not support the HTTP protocol version used in the request. + +- 506 Variant Also Negotiates + + - Transparent content negotiation for the request results in a circular + reference. + +- 507 Insufficient Storage + + - The server is unable to store the representation needed to complete the + request. + +- 508 Loop Detected + + - The server detected an infinite loop while processing the request (sent in + lieu of 208 Already Reported). + +- 510 Not Extended + + - Further extensions to the request are required for the server to fulfil it. + +### Response Headers Reserved for Future Use + +The following response headers are not currently in use. Future versions of the +API could return them. + +- 206 Partial Content + + - The server is delivering only part of the resource (byte serving) due to a + range header sent by the client. + +- 300 Multiple Choices + + - Indicates multiple options for the resource from which the client may choose + (via agent-driven content negotiation). + +- 407 Proxy Authentication Required + + - The client must first authenticate itself with the proxy. + +- 408 Request Timeout + + - The server timed out waiting for the request. According to HTTP + specifications: "The client did not produce a request within the time that + the server was prepared to wait. The client MAY repeat the request without + modifications at any later time." + +- 410 Gone + + - Indicates that the resource requested is no longer available and will not be + available again. + +- 416 Range Not Satisfiable + + - The client has asked for a portion of the file (byte serving), but the + server cannot supply that portion. + +- 417 Expectation Failed + + - The server cannot meet the requirements of the Expect request-header field. + +- 421 Misdirected Request + + - The request was directed at a server that is not able to produce a response. + +- 424 Failed Dependency + + - The request failed due to failure of a previous request. + +- 426 Upgrade Required + + - The client should switch to a different protocol such as TLS/1.0, given in + the Upgrade header field. + +- 429 Too Many Requests + + - 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) + +## 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. + +- `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-Filter.md b/Documentation/REST-API/Resources-Filter.md new file mode 100644 index 000000000..2235209b1 --- /dev/null +++ b/Documentation/REST-API/Resources-Filter.md @@ -0,0 +1,151 @@ +# Filter Resource + +A filter resource represents an instance of a filter inside MaxScale. Multiple +services can use the same filter and a single service can use multiple filters. + +## Resource Operations + +### Get a filter + +Get a single filter. The _:name_ in the URI must be a valid filter name with all +whitespace replaced with hyphens. The filter names are case-insensitive. + +``` +GET /filters/:name +``` + +#### Response + +``` +Status: 200 OK + +{ + "name": "Query Logging Filter", + "module": "qlafilter", + "parameters": { + "filebase": { + "value": "/var/log/maxscale/qla/log.", + "configurable": false + }, + "match": { + "value": "select.*from.*t1", + "configurable": true + } + }, + "services": [ + "/services/my-service", + "/services/my-second-service" + ] +} +``` + +#### Supported Request Parameter + +- `fields` + +### Get all filters + +Get all filters. + +``` +GET /filters +``` + +#### Response + +``` +Status: 200 OK + +[ + { + "name": "Query Logging Filter", + "module": "qlafilter", + "parameters": { + "filebase": { + "value": "/var/log/maxscale/qla/log.", + "configurable": false + }, + "match": { + "value": "select.*from.*t1", + "configurable": true + } + }, + "services": [ + "/services/my-service", + "/services/my-second-service + ] + }, + { + "name": "DBFW Filter", + "module": "dbfwfilter", + "parameters": { + { + "name": "rules", + "value": "/etc/maxscale-rules", + "configurable": false + } + }, + "services": [ + "/services/my-second-service + ] + } +] +``` + +#### Supported Request Parameter + +- `fields` +- `range` + +### Update a filter + +**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 filter. The _:name_ in the URI must map to a filter name +and the request body must be a valid JSON Patch document which is applied to the +resource. + +``` +PATCH /filter/:name +``` + +### Modifiable Fields + +|Field |Type |Description | +|------------|-------|---------------------------------| +|parameters |object |Module specific filter parameters| + +``` +[ + { "op": "replace", "path": "/parameters/rules/value", "value": "/etc/new-rules" }, + { "op": "add", "path": "/parameters/action/value", "value": "allow" } +] +``` + +#### Response + +Response contains the modified resource. + +``` +Status: 200 OK + +{ + "name": "DBFW Filter", + "module": "dbfwfilter", + "parameters": { + "rules": { + "value": "/etc/new-rules", + "configurable": false + }, + "action": { + "value": "allow", + "configurable": true + } + } + "services": [ + "/services/my-second-service" + ] +} +``` diff --git a/Documentation/REST-API/Resources-MaxScale.md b/Documentation/REST-API/Resources-MaxScale.md new file mode 100644 index 000000000..f2959c1d4 --- /dev/null +++ b/Documentation/REST-API/Resources-MaxScale.md @@ -0,0 +1,216 @@ +# MaxScale Resource + +The MaxScale resource represents a MaxScale instance and it is the core on top +of which the modules build upon. + +## Resource Operations + +## Get global information + +Retrieve global information about a MaxScale instance. This includes various +file locations, configuration options and version information. + +``` +GET /maxscale +``` + +#### Response + +``` +Status: 200 OK + +{ + "config": "/etc/maxscale.cnf", + "cachedir": "/var/cache/maxscale/", + "datadir": "/var/lib/maxscale/" + "libdir": "/usr/lib64/maxscale/", + "piddir": "/var/run/maxscale/", + "execdir": "/usr/bin/", + "languagedir": "/var/lib/maxscale/", + "user": "maxscale", + "threads": 4, + "version": "2.1.0", + "commit": "12e7f17eb361e353f7ac413b8b4274badb41b559" + "started": "Wed, 31 Aug 2016 23:29:26 +0300" +} +``` + +#### Supported Request Parameter + +- `fields` + +## Get thread information + +Get detailed information and statistics about the threads. + +``` +GET /maxscale/threads +``` + +#### Response + +``` +Status: 200 OK + +{ + "load_average": { + "historic": 1.05, + "current": 1.00, + "1min": 0.00, + "5min": 0.00, + "15min": 0.00 + }, + "threads": [ + { + "id": 0, + "state": "processing", + "file_descriptors": 1, + "event": [ + "in", + "out" + ], + "run_time": 300 + }, + { + "id": 1, + "state": "polling", + "file_descriptors": 0, + "event": [], + "run_time": 0 + } + ] +} +``` + +#### Supported Request Parameter + +- `fields` + +## Get logging information + +Get information about the current state of logging, enabled log files and the +location where the log files are stored. + +``` +GET /maxscale/logs +``` + +#### Response + +``` +Status: 200 OK + +{ + "logdir": "/var/log/maxscale/", + "maxlog": true, + "syslog": false, + "log_levels": { + "error": true, + "warning": true, + "notice": true, + "info": false, + "debug": false + }, + "log_augmentation": { + "function": true + }, + "log_throttling": { + "limit": 8, + "window": 2000, + "suppression": 10000 + }, + "last_flushed": "Wed, 31 Aug 2016 23:29:26 +0300" +} +``` + +#### Supported Request Parameter + +- `fields` + +## Flush and rotate log files + +Flushes any pending messages to disk and reopens the log files. The body of the +message is ignored. + +``` +POST /maxscale/logs/flush +``` + +#### Response + +``` +Status: 204 No Content +``` + +## Get task schedule + +Retrieve all pending tasks that are queued for execution. + +``` +GET /maxscale/tasks +``` + +#### Response + +``` +Status: 200 OK + +[ + { + "name": "Load Average", + "type": "repeated", + "frequency": 10, + "next_due": "Fri Sep 9 14:12:37 2016" + } +} +``` + +#### Supported Request Parameter + +- `fields` + +## Get loaded modules + +Retrieve information about all loaded modules. This includes version, API and +maturity information. + +``` +GET /maxscale/modules +``` + +#### Response + +``` +Status: 200 OK + +[ + { + "name": "MySQLBackend", + "type": "Protocol", + "version": "V2.0.0", + "api_version": "1.1.0", + "maturity": "GA" + }, + { + "name": "qlafilter", + "type": "Filter", + "version": "V1.1.1", + "api_version": "1.1.0", + "maturity": "GA" + }, + { + "name": "readwritesplit", + "type": "Router", + "version": "V1.1.0", + "api_version": "1.0.0", + "maturity": "GA" + } +} +``` + +#### Supported Request Parameter + +- `fields` +- `range` + +TODO: Add epoll statistics and rest of the supported methods. diff --git a/Documentation/REST-API/Resources-Monitor.md b/Documentation/REST-API/Resources-Monitor.md new file mode 100644 index 000000000..043af6545 --- /dev/null +++ b/Documentation/REST-API/Resources-Monitor.md @@ -0,0 +1,176 @@ +# Monitor Resource + +A monitor resource represents a monitor inside MaxScale that monitors one or +more servers. + +## Resource Operations + +### Get a monitor + +Get a single monitor. The _:name_ in the URI must be a valid monitor name with +all whitespace replaced with hyphens. The monitor names are case-insensitive. + +``` +GET /monitors/:name +``` + +#### Response + +``` +Status: 200 OK + +{ + "name": "MySQL Monitor", + "module": "mysqlmon", + "state": "started", + "monitor_interval": 2500, + "connect_timeout": 5, + "read_timeout": 2, + "write_timeout": 3, + "servers": [ + "/servers/db-serv-1", + "/servers/db-serv-2", + "/servers/db-serv-3" + ] +} +``` + +#### Supported Request Parameter + +- `fields` + +### Get all monitors + +Get all monitors. + +``` +GET /monitors +``` + +#### Response + +``` +Status: 200 OK + +[ + { + "name": "MySQL Monitor", + "module": "mysqlmon", + "state": "started", + "monitor_interval": 2500, + "connect_timeout": 5, + "read_timeout": 2, + "write_timeout": 3, + "servers": [ + "/servers/db-serv-1", + "/servers/db-serv-2", + "/servers/db-serv-3" + ] + }, + { + "name": "Galera Monitor", + "module": "galeramon", + "state": "started", + "monitor_interval": 5000, + "connect_timeout": 10, + "read_timeout": 5, + "write_timeout": 5, + "servers": [ + "/servers/db-galera-1", + "/servers/db-galera-2", + "/servers/db-galera-3" + ] + } +] +``` + +#### Supported Request Parameter + +- `fields` +- `range` + +### Stop a monitor + +Stops a started monitor. + +``` +PUT /monitor/:name/stop +``` + +#### Response + +``` +Status: 204 No Content +``` + +### Start a monitor + +Starts a stopped monitor. + +``` +PUT /monitor/:name/start +``` + +#### Response + +``` +Status: 204 No Content +``` + +### Update a monitor + +**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 monitor. The _:name_ in the URI must map to a monitor name +and the request body must be a valid JSON Patch document which is applied to the +resource. + +``` +PATCH /monitor/:name +``` + +### Modifiable Fields + +The following values can be modified with the PATCH method. + +|Field |Type |Description | +|-----------------|------------|---------------------------------------------------| +|servers |string array|Servers monitored by this monitor | +|monitor_interval |number |Monitoring interval in milliseconds | +|connect_timeout |number |Connection timeout in seconds | +|read_timeout |number |Read timeout in seconds | +|write_timeout |number |Write timeout in seconds | + +``` +[ + { "op": "remove", "path": "/servers/0" }, + { "op": "replace", "path": "/monitor_interval", "value": 2000 }, + { "op": "replace", "path": "/connect_timeout", "value": 2 }, + { "op": "replace", "path": "/read_timeout", "value": 2 }, + { "op": "replace", "path": "/write_timeout", "value": 2 } +] +``` + +#### Response + +Response contains the modified resource. + +``` +Status: 200 OK + +{ + "name": "MySQL Monitor", + "module": "mysqlmon", + "servers": [ + "/servers/db-serv-2", + "/servers/db-serv-3" + ], + "state": "started", + "monitor_interval": 2000, + "connect_timeout": 2, + "read_timeout": 2, + "write_timeout": 2 +} +``` diff --git a/Documentation/REST-API/Resources-Server.md b/Documentation/REST-API/Resources-Server.md new file mode 100644 index 000000000..a73b0d531 --- /dev/null +++ b/Documentation/REST-API/Resources-Server.md @@ -0,0 +1,207 @@ +# Server Resource + +A server resource represents a backend database server. + +## Resource Operations + +### Get a server + +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. + +``` +GET /servers/:name +``` + +#### Response + +``` +Status: 200 OK + +{ + "name": "db-serv-1", + "address": "192.168.121.58", + "port": 3306, + "protocol": "MySQLBackend", + "status": [ + "master", + "running" + ], + "parameters": { + "report_weight": 10, + "app_weight": 2 + } +} +``` + +**Note**: The _parameters_ field contains all custom parameters for + servers, including the server weighting parameters. + +#### Supported Request Parameter + +- `fields` + +### Get all servers + +``` +GET /servers +``` + +#### Response + +``` +Status: 200 OK + +[ + { + "name": "db-serv-1", + "address": "192.168.121.58", + "port": 3306, + "protocol": "MySQLBackend", + "status": [ + "master", + "running" + ], + "parameters": { + "report_weight": 10, + "app_weight": 2 + } + }, + { + "name": "db-serv-2", + "address": "192.168.121.175", + "port": 3306, + "status": [ + "slave", + "running" + ], + "protocol": "MySQLBackend", + "parameters": { + "app_weight": 6 + } + } +] +``` + +#### Supported Request Parameter + +- `fields` +- `range` + +### Update a server + +**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 server. 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 +Patch document which is applied to the resource. + +``` +PATCH /servers/:name +``` + +### Modifiable Fields + +|Field |Type |Description | +|-----------|------------|-----------------------------------------------------------------------------| +|address |string |Server address | +|port |number |Server port | +|parameters |object |Server extra parameters | +|state |string array|Server state, array of `master`, `slave`, `synced`, `running` or `maintenance`. An empty array is interpreted as a server that is down.| + +``` +{ + { "op": "replace", "path": "/address", "value": "192.168.0.100" }, + { "op": "replace", "path": "/port", "value": 4006 }, + { "op": "add", "path": "/state/0", "value": "maintenance" }, + { "op": "replace", "path": "/parameters/report_weight", "value": 1 } +} +``` + +#### Response + +Response contains the modified resource. + +``` +Status: 200 OK + +{ + "name": "db-serv-1", + "protocol": "MySQLBackend", + "address": "192.168.0.100", + "port": 4006, + "state": [ + "maintenance", + "running" + ], + "parameters": { + "report_weight": 1, + "app_weight": 2 + } +} +``` + +### 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 +``` diff --git a/Documentation/REST-API/Resources-Service.md b/Documentation/REST-API/Resources-Service.md new file mode 100644 index 000000000..11c15d4e4 --- /dev/null +++ b/Documentation/REST-API/Resources-Service.md @@ -0,0 +1,272 @@ +# 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 +``` diff --git a/Documentation/REST-API/Resources-Session.md b/Documentation/REST-API/Resources-Session.md new file mode 100644 index 000000000..03f90d0d7 --- /dev/null +++ b/Documentation/REST-API/Resources-Session.md @@ -0,0 +1,138 @@ +# Session Resource + +A session consists of a client connection, any number of related backend +connections, a router module session and possibly filter module sessions. Each +session is created on a service and a service can have multiple sessions. + +## Resource Operations + +### Get a session + +Get a single session. _:id_ must be a valid session ID. + +``` +GET /sessions/:id +``` + +#### Response + +``` +Status: 200 OK + +{ + "id": 1, + "state": "Session ready for routing", + "user": "jdoe", + "address": "192.168.0.200", + "service": "/services/my-service", + "connected": "Wed Aug 31 03:03:12 2016", + "idle": 260 +} +``` + +#### Supported Request Parameter + +- `fields` + +### Get all sessions + +Get all sessions. + +``` +GET /sessions +``` + +#### Response + +``` +Status: 200 OK + +[ + { + "id": 1, + "state": "Session ready for routing", + "user": "jdoe", + "address": "192.168.0.200", + "service": "/services/My-Service", + "connected": "Wed Aug 31 03:03:12 2016", + "idle": 260 + }, + { + "id": 2, + "state": "Session ready for routing", + "user": "dba", + "address": "192.168.0.201", + "service": "/services/My-Service", + "connected": "Wed Aug 31 03:10:00 2016", + "idle": 1 + } +] +``` + +#### Supported Request Parameter + +- `fields` +- `range` + +### Get all connections created by a session + +Get all backend connections created by a session. _:id_ must be a valid session ID. + +``` +GET /sessions/:id/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-02", + "service": "/services/my-service", + "statistics": { + "reads": 0 + "writes": 0 + "buffered_writes": 0 + "high_water_events": 0 + "low_water_events": 0 + } + } +] +``` + +#### Supported Request Parameter + +- `fields` +- `range` + +### Close a session + +Close a session. This will forcefully close the client connection and any +backend connections. + +``` +DELETE /sessions/:id +``` + +#### Response + +``` +Status: 204 No Content +``` diff --git a/Documentation/REST-API/Resources-User.md b/Documentation/REST-API/Resources-User.md new file mode 100644 index 000000000..84c8fc9f8 --- /dev/null +++ b/Documentation/REST-API/Resources-User.md @@ -0,0 +1,81 @@ +# Admin User Resource + +Admin users represent administrative users that are able to query and change +MaxScale's configuration. + +## Resource Operations + +### Get all users + +Get all administrative users. + +``` +GET /users +``` + +#### Response + +``` +Status: 200 OK + +[ + { + "name": "jdoe" + }, + { + "name": "dba" + }, + { + "name": "admin" + } +] + +#### Supported Request Parameter + +- `fields` +- `range` + +### Create a user + +Create a new administrative user. + +``` +PUT /users +``` + +### Modifiable Fields + +All of the following fields need to be defined in the request body. + +|Field |Type |Description | +|---------|------|-------------------------| +|name |string|Username, consisting of alphanumeric characters| +|password |string|Password for the new user| + +``` +{ + "name": "foo", + "password": "bar" +} +``` + +#### Response + +``` +Status: 204 No Content +``` + +### Delete a user + +Delete a user. The _:name_ part of the URI must be a valid user name. The user +names are case-insensitive. + +``` +DELETE /users/:name +``` + +#### Response + +``` +Status: 204 No Content +```