diff --git a/Documentation/REST-API/API.md b/Documentation/REST-API/API.md deleted file mode 100644 index afa08573b..000000000 --- a/Documentation/REST-API/API.md +++ /dev/null @@ -1,453 +0,0 @@ -# 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 deleted file mode 100644 index 2235209b1..000000000 --- a/Documentation/REST-API/Resources-Filter.md +++ /dev/null @@ -1,151 +0,0 @@ -# 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 deleted file mode 100644 index f2959c1d4..000000000 --- a/Documentation/REST-API/Resources-MaxScale.md +++ /dev/null @@ -1,216 +0,0 @@ -# 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 deleted file mode 100644 index 043af6545..000000000 --- a/Documentation/REST-API/Resources-Monitor.md +++ /dev/null @@ -1,176 +0,0 @@ -# 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 deleted file mode 100644 index a73b0d531..000000000 --- a/Documentation/REST-API/Resources-Server.md +++ /dev/null @@ -1,207 +0,0 @@ -# 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 deleted file mode 100644 index 11c15d4e4..000000000 --- a/Documentation/REST-API/Resources-Service.md +++ /dev/null @@ -1,272 +0,0 @@ -# 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 deleted file mode 100644 index 03f90d0d7..000000000 --- a/Documentation/REST-API/Resources-Session.md +++ /dev/null @@ -1,138 +0,0 @@ -# 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 deleted file mode 100644 index 84c8fc9f8..000000000 --- a/Documentation/REST-API/Resources-User.md +++ /dev/null @@ -1,81 +0,0 @@ -# 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 -```