From 59e615eb3c01414ef9508a08d5211f214b1e1c42 Mon Sep 17 00:00:00 2001 From: Markus Makela Date: Tue, 26 Jul 2016 16:50:51 +0300 Subject: [PATCH] Create initial REST API documentation The Resources document lists all currently known resources and will be converted to a list of separate resource documents once the individual resource documents are done. The Headers and Response Codes document contains a list of request and response headers and the HTTP return codes. This is a work in progress and will be expanded upon. Added initial versions of the filter, monitor, session and user resource documents. These provide information about various parts of MaxScale and allow interaction. All PATCH operations expect a JSON Patch type document in the request body. Examples modified accordingly. Add MaxScale resource document which describes the resources that give the global configuration options and show statistics. The resources that link to other resources provide values as a list of relative links. This reduces the amount of sent data when the client doesn't require all parts of the resource. Since the updating is not yet implement, it should be stated that the update API will most likely be modified at some point. The module resource is similar to `maxadmin show modules` and the log resource contains status information about logs. The log resource also has an "action" resource at `/maxscale/logs/flush` which flushes logs to disk and rotates them. Added start and stop entry points for services and monitors. Also added missing service parameters to the list of parameters that can be updated. The documentation lists listeners as a sub-resource of the service. This allows the listeners of a particular service to be queried. --- Documentation/Documentation-Contents.md | 1 + Documentation/REST-API/API.md | 453 +++++++++++++++++++ Documentation/REST-API/Resources-Filter.md | 151 +++++++ Documentation/REST-API/Resources-MaxScale.md | 216 +++++++++ Documentation/REST-API/Resources-Monitor.md | 176 +++++++ Documentation/REST-API/Resources-Server.md | 207 +++++++++ Documentation/REST-API/Resources-Service.md | 272 +++++++++++ Documentation/REST-API/Resources-Session.md | 138 ++++++ Documentation/REST-API/Resources-User.md | 81 ++++ 9 files changed, 1695 insertions(+) create mode 100644 Documentation/REST-API/API.md create mode 100644 Documentation/REST-API/Resources-Filter.md create mode 100644 Documentation/REST-API/Resources-MaxScale.md create mode 100644 Documentation/REST-API/Resources-Monitor.md create mode 100644 Documentation/REST-API/Resources-Server.md create mode 100644 Documentation/REST-API/Resources-Service.md create mode 100644 Documentation/REST-API/Resources-Session.md create mode 100644 Documentation/REST-API/Resources-User.md 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 +```