Update REST API documentation

Updated and unified the documentation of the REST API.

Documentation/REST-API/API.md

@@ -136,9 +136,9 @@ by this API.
 Credentials for authentication. This header should consist of a HTTP Basic
 Access authentication type payload which is the base64 encoded value of the
 username and password joined by a colon e.g. `Base64("maxuser:maxpwd")`. The
-REST API uses the same users as the MaxAdmin interface. For more details about
+REST API uses the same users as the MaxAdmin network interface. For more details
-MaxScale administrative users, refer to the [MaxAdmin](../Reference/MaxAdmin.md)
+about MaxScale administrative users, refer to the
-documentation.
+[MaxAdmin](../Reference/MaxAdmin.md) documentation.
 
 #### Content-Type
 
@@ -146,7 +146,7 @@ All PUT and POST requests must use the `Content-Type: application/json` media
 type and the request body must be a complete and valid JSON representation of a
 resource. All PATCH requests must use the `Content-Type: application/json` media
 type and the request body must be a JSON document containing a partial
-definition of the original resource.
+definition of the modified resource.
 
 #### Host
 

Documentation/REST-API/Resources-Filter.md

@@ -111,8 +111,7 @@ As the service to filter relationship is ordered (filters are applied in the
 order they are listed), filter to service relationships cannot be defined at
 creation time.
 
-The following example defines a request body which creates the new filter,
+The following example defines a request body which creates a new filter.
-_test-filter_, and assigns it to a service.
 
 ```javascript
 {

Documentation/REST-API/Resources-MaxScale.md

@@ -7,13 +7,13 @@ of which the modules build upon.
 
 ## Get global information
 
-Retrieve global information about a MaxScale instance. This includes various
-file locations, configuration options and version information.
-
 ```
 GET /v1/maxscale
 ```
 
+Retrieve global information about a MaxScale instance. This includes various
+file locations, configuration options and version information.
+
 #### Response
 
 `Status: 200 OK`
@@ -67,6 +67,10 @@ GET /v1/maxscale
 
 ## Update MaxScale parameters
 
+```
+PATCH /v1/maxscale
+```
+
 Update MaxScale parameters. The request body must define updated values for the
 `data.attributes.parameters` object. The following parameters can be altered:
 
@@ -77,10 +81,6 @@ Update MaxScale parameters. The request body must define updated values for the
 - [admin_log_auth_failures](../Getting-Started/Configuration-Guide.md#admin_log_auth_failures)
 - [passive](../Getting-Started/Configuration-Guide.md#passive)
 
-```
-PATCH /v1/maxscale
-```
-
 #### Response
 
 Parameters modified:
@@ -93,14 +93,14 @@ Invalid JSON body:
 
 ## Get thread information
 
-Get the information and statistics of a particular thread. The _:id_ in
-the URI must map to a valid thread number between 0 and the configured
-value of `threads`.
-
 ```
 GET /v1/maxscale/threads/:id
 ```
 
+Get the information and statistics of a particular thread. The _:id_ in
+the URI must map to a valid thread number between 0 and the configured
+value of `threads`.
+
 #### Response
 
 `Status: 200 OK`
@@ -143,12 +143,12 @@ GET /v1/maxscale/threads/:id
 
 ## Get information for all threads
 
-Get the informatino for all threads. Returns a collection of threads resources.
-
 ```
 GET /v1/maxscale/threads
 ```
 
+Get the information for all threads. Returns a collection of threads resources.
+
 #### Response
 
 `Status: 200 OK`
@@ -277,13 +277,13 @@ GET /v1/maxscale/threads
 
 ## Get logging information
 
-Get information about the current state of logging, enabled log files and the
-location where the log files are stored.
-
 ```
 GET /v1/maxscale/logs
 ```
 
+Get information about the current state of logging, enabled log files and the
+location where the log files are stored.
+
 #### Response
 
 `Status: 200 OK`
@@ -326,14 +326,14 @@ GET /v1/maxscale/logs
 
 ## Update logging parameters
 
-Update logging parameters. The request body must define updated values for the
-`data.attributes.parameters` object. All logging parameters apart from
-`log_to_shm` can be altered at runtime.
-
 ```
 PATCH /v1/maxscale/logs
 ```
 
+Update logging parameters. The request body must define updated values for the
+`data.attributes.parameters` object. All logging parameters apart from
+`log_to_shm` can be altered at runtime.
+
 #### Response
 
 Parameters modified:
@@ -346,25 +346,25 @@ Invalid JSON body:
 
 ## Flush and rotate log files
 
-Flushes any pending messages to disk and reopens the log files. The body of the
-message is ignored.
-
 ```
 POST /v1/maxscale/logs/flush
 ```
 
+Flushes any pending messages to disk and reopens the log files. The body of the
+message is ignored.
+
 #### Response
 
 `Status: 204 No Content`
 
 ## Get task schedule
 
-Retrieve all pending tasks that are queued for execution.
-
 ```
 GET /v1/maxscale/tasks
 ```
 
+Retrieve all pending tasks that are queued for execution.
+
 #### Response
 
 `Status: 200 OK`
@@ -378,15 +378,15 @@ GET /v1/maxscale/tasks
 }
 ```
 
-## Get loaded modules
+## Get a loaded module
-
-Retrieve information about a loaded module. This includes version, API and
-maturity information as well as all the parameters that the module defines.
 
 ```
-GET /v1/maxscale/modules
+GET /v1/maxscale/modules/:name
 ```
 
+Retrieve information about a loaded module. The _:name_ must be the name of a
+valid loaded module.
+
 #### Response
 
 `Status: 200 OK`
@@ -467,12 +467,12 @@ GET /v1/maxscale/modules
 
 ## Get all loaded modules
 
-Retrieve information about all loaded modules.
-
 ```
 GET /v1/maxscale/modules
 ```
 
+Retrieve information about all loaded modules.
+
 #### Response
 
 `Status: 200 OK`
@@ -519,15 +519,6 @@ GET /v1/maxscale/modules
 
 ## Call a module command
 
-Modules can expose commands that can be called via the REST API. The module
-resource lists all commands in the `data.attributes.commands` list. Each value
-is a command sub-resource identified by its `id` field and the HTTP method the
-command uses is defined by the `attributes.method` field.
-
-The _:module_ in the URI must be a valid name of a loaded module and _:command_
-must be a valid command identifier that is exposed by that module. All
-parameters to the module commands are passed as HTTP request parameters.
-
 For read-only commands:
 
 ```
@@ -540,6 +531,15 @@ For commands that can modify data:
 POST /v1/maxscale/modules/:module/:command
 ```
 
+Modules can expose commands that can be called via the REST API. The module
+resource lists all commands in the `data.attributes.commands` list. Each value
+is a command sub-resource identified by its `id` field and the HTTP method the
+command uses is defined by the `attributes.method` field.
+
+The _:module_ in the URI must be a valid name of a loaded module and _:command_
+must be a valid command identifier that is exposed by that module. All
+parameters to the module commands are passed as HTTP request parameters.
+
 Here is an example POST requests to the dbfwfilter module command _reload_ with
 two parameters, the name of the filter instance and the path to a file:
 

Documentation/REST-API/Resources-Monitor.md

@@ -7,13 +7,13 @@ more servers.
 
 ### 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-sensitive.
-
 ```
 GET /v1/monitors/:name
 ```
 
+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-sensitive.
+
 #### Response
 
 `Status: 200 OK`
@@ -110,12 +110,12 @@ GET /v1/monitors/:name
 
 ### Get all monitors
 
-Get all monitors.
-
 ```
 GET /v1/monitors
 ```
 
+Get all monitors.
+
 #### Response
 
 `Status: 200 OK`
@@ -214,19 +214,33 @@ GET /v1/monitors
 
 ### Create a monitor
 
-Create a new monitor. The request body must define the `/data/id`
-field with the name of the monitor, the `/data/type` field with the
-value of `monitors` and the `/data/attributes/module` field with the
-monitor module for this monitor. All of the monitor parameters can
-be defined at creation time.
-
 ```
 POST /v1/monitors
 ```
 
-The following example defines a request body which creates the new monitor,
+Create a new monitor. The request body must define at least the following
-_test-monitor_, and assigns two servers to be monitored by it. It also defines
+fields.
-a custom value for the _monitor_interval_ parameter.
+
+* `data.id`
+  * Name of the monitor
+
+* `data.type`
+  * Type of the object, must be `monitors`
+
+* `data.attributes.module`
+  * The monitor module to use
+
+* `data.attributes.parameters.user`
+  * The [`user`](../Getting-Started/Configuration-Guide.md#password) to use
+
+* `data.attributes.parameters.password`
+  * The [`password`](../Getting-Started/Configuration-Guide.md#password) to use
+
+All monitor parameters can be defined at creation time.
+
+The following example defines a request body which creates a new monitor and
+assigns two servers to be monitored by it. It also defines a custom value for
+the _monitor_interval_ parameter.
 
 ```javascript
 {
@@ -236,7 +250,9 @@ a custom value for the _monitor_interval_ parameter.
         "attributes": {
             "module": "mariadbmon", // The monitor uses the mariadbmon module
             "parameters": { // Monitor parameters
-                "monitor_interval": 1000
+                "monitor_interval": 1000,
+                "user": "maxuser,
+                "password": "maxpwd"
             }
         },
         "relationships": { // List of server relationships that this monitor uses
@@ -265,16 +281,18 @@ Monitor is created:
 
 ### Update a monitor
 
-The :name in the URI must map to a monitor name with all whitespace replaced with
-hyphens. The request body must be a valid JSON document representing the modified monitor.
-
 ```
 PATCH /v1/monitors/:name
 ```
 
+The :name in the URI must map to a monitor name with all whitespace replaced
+with hyphens. The request body must be a valid JSON document representing the
+modified monitor.
+
 ### Modifiable Fields
 
 The following standard server parameter can be modified.
+
 - [user](../Monitors/Monitor-Common.md#user)
 - [password](../Monitors/Monitor-Common.md#password)
 - [monitor_interval](../Monitors/Monitor-Common.md#monitor_interval)
@@ -283,10 +301,9 @@ The following standard server parameter can be modified.
 - [backend_read_timeout](../Monitors/Monitor-Common.md#backend_read_timeout)
 - [backend_connect_attempts](../Monitors/Monitor-Common.md#backend_connect_attempts)
 
-Refer to the documentation on these parameters for valid values.
+In addition to these standard parameters, the monitor specific parameters can
-
+also be modified. Refer to the monitor module documentation for details on these
-In addition to these standard parameters, the monitor specific parameters can also be
+parameters.
-modified. Refer to the monitor module documentation for details on these parameters.
 
 #### Response
 
@@ -348,14 +365,13 @@ Invalid JSON body:
 
 ### Destroy a monitor
 
-Destroy a created monitor. The monitor must not have relationships to any
-servers and if it does a PATCH request which removes these relationships is
-required before a DELETE request for the monitor can be made.
-
 ```
 DELETE /v1/monitors/:name/stop
 ```
 
+Destroy a created monitor. The monitor must not have relationships to any
+servers in order to be destroyed.
+
 #### Response
 
 Monitor is deleted:
@@ -368,12 +384,12 @@ Monitor could not be deleted:
 
 ### Stop a monitor
 
-Stops a started monitor.
-
 ```
 PUT /v1/monitors/:name/stop
 ```
 
+Stops a started monitor.
+
 #### Response
 
 Monitor is stopped:
@@ -382,12 +398,12 @@ Monitor is stopped:
 
 ### Start a monitor
 
-Starts a stopped monitor.
-
 ```
 PUT /v1/monitors/:name/start
 ```
 
+Starts a stopped monitor.
+
 #### Response
 
 Monitor is started:

Documentation/REST-API/Resources-Server.md

@@ -232,11 +232,23 @@ Response contains a resource collection with all servers.
 POST /v1/servers
 ```
 
-Create a new server by defining the resource. The posted object must define the
+Create a new server by defining the resource. The posted object must define at
-_data.id_ field with the name of the server and the
+least the following fields.
-_data.atttributes.parameters_ field with JSON object containing values for the
+
-_address_ and _port_ parameters. The following is the minimal required JSON
+* `data.id`
-object for defining a new server.
+  * Name of the server
+
+* `data.type`
+  * Type of the object, must be `servers`
+
+* `data.attributes.parameters.address`
+  * The [`address`](../Getting-Started/Configuration-Guide.md#address) to use
+
+* `data.attributes.parameters.port`
+  * The [`port`](../Getting-Started/Configuration-Guide.md#port) to use
+
+
+The following is the minimal required JSON object for defining a new server.
 
 ```javascript
 {
@@ -246,8 +258,7 @@ object for defining a new server.
         "attributes": {
             "parameters": {
                 "address": "127.0.0.1",
-                "port": 3003,
+                "port": 3003
-                "protocol": "MariaDBBackend"
             }
         }
     }
@@ -265,8 +276,7 @@ new servers to be created and immediately taken into use.
         "attributes": {
             "parameters": {
                 "address": "127.0.0.1",
-                "port": 3002,
+                "port": 3002
-                "protocol": "MariaDBBackend"
             }
         },
         "relationships": {
@@ -301,12 +311,12 @@ The following parameters can be defined when a server is being created.
 - [port](../Getting-Started/Configuration-Guide.md#port)
 - [protocol](../Getting-Started/Configuration-Guide.md#protocol)
 - [authenticator](../Getting-Started/Configuration-Guide.md#authenticator)
-- [authenticator_options](../Getting-Started/Configuration-Guide.md#authenticator-options)
 - [ssl_key](../Getting-Started/Configuration-Guide.md#ssl_key)
 - [ssl_cert](../Getting-Started/Configuration-Guide.md#ssl_cert)
 - [ssl_ca_cert](../Getting-Started/Configuration-Guide.md#ssl_ca_cert)
 - [ssl_version](../Getting-Started/Configuration-Guide.md#ssl_version)
 - [ssl_cert_verify_depth](../Getting-Started/Configuration-Guide.md#ssl_cert_verify_depth)
+- [ssl_verify_peer_certificate](../Getting-Started/Configuration-Guide.md#ssl_verify_peer_certificate)
 
 #### Response
 

Documentation/REST-API/Resources-Service.md

@@ -7,13 +7,13 @@ collection of network listeners, filters, a router and a set of backend servers.
 
 ### 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 /v1/services/:name
 ```
 
+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.
+
 #### Response
 
 `Status: 200 OK`
@@ -88,12 +88,12 @@ GET /v1/services/:name
 
 ### Get all services
 
-Get all services.
-
 ```
 GET /v1/services
 ```
 
+Get all services.
+
 #### Response
 
 `Status: 200 OK`
@@ -239,13 +239,13 @@ least the following fields.
 * `data.type`
   * Type of the object, must be `services`
 
-* `data.atttributes.router`
+* `data.attributes.router`
   * The router module to use
 
-* `data.atttributes.parameters.user`
+* `data.attributes.parameters.user`
   * The [`user`](../Getting-Started/Configuration-Guide.md#password) to use
 
-* `data.atttributes.parameters.password`
+* `data.attributes.parameters.password`
   * The [`password`](../Getting-Started/Configuration-Guide.md#password) to use
 
 The `data.attributes.parameters` object is used to define router and service
@@ -377,14 +377,14 @@ GET /v1/services/:name/listeners
 
 ### Get a single service listener
 
-Get the listeners of a service. The _:name_ in the URI must be a valid service
-name and _:listener_ must be a valid listener name, both with all whitespace
-replaced with hyphens.
-
 ```
 GET /v1/services/:name/listeners/:listener
 ```
 
+Get the listeners of a service. The _:name_ in the URI must be a valid service
+name and _:listener_ must be a valid listener name, both with all whitespace
+replaced with hyphens.
+
 #### Response
 
 `Status: 200 OK`
@@ -410,7 +410,6 @@ GET /v1/services/:name/listeners/:listener
 
 ### Create a new listener
 
-
 ```
 POST /v1/services/:name/listeners
 ```
@@ -479,13 +478,13 @@ Listener cannot be deleted:
 
 ### 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 /v1/services/:name
 ```
 
+The _:name_ in the URI must map to a service name and the request body must be a
+JSON object which is interpreted as the new definition of the service.
+
 All standard service parameters can be modified. Refer to the
 [service](../Getting-Started/Configuration-Guide.md#service) documentation on
 the details of these parameters.
@@ -495,6 +494,20 @@ at runtime if the router module supports it. Refer to the individual router
 documentation for more details on whether the router supports it and which
 parameters can be updated at runtime.
 
+The following example modifies a service by changing the `user` parameter to `admin`.
+
+```javascript
+{
+    "data": {
+        "attributes": {
+            "parameters": {
+                "user": "admin"
+            }
+        }
+    }
+}
+```
+
 #### Response
 
 Service is modified:
@@ -504,12 +517,12 @@ Service is modified:
 ### Update service relationships
 
 ```
-PATCH /v1/services/:name/relationships/servers
+PATCH /v1/services/:name/relationships/:type
-PATCH /v1/services/:name/relationships/filters
 ```
 
 The _:name_ in the URI must map to a service name with all whitespace replaced
-with hyphens.
+with hyphens. The _:type_ in the URI must be either _servers_ or _filters_,
+depending on which relationship is being modified.
 
 The request body must be a JSON object that defines only the _data_ field. The
 value of the _data_ field must be an array of relationship objects that define
@@ -524,7 +537,8 @@ existing relationships of this type for the service. Both `servers` and
  for more details.
 
 The following is an example request and request body that defines a single
-server relationship for a service.
+server relationship for a service that is equivalent to a `servers=my-server`
+parameter.
 
 ```
 PATCH /v1/services/my-rw-service/relationships/servers
@@ -560,12 +574,12 @@ Invalid JSON body:
 
 ### Stop a service
 
-Stops a started service.
-
 ```
 PUT /v1/services/:name/stop
 ```
 
+Stops a started service.
+
 #### Response
 
 Service is stopped:
@@ -574,12 +588,12 @@ Service is stopped:
 
 ### Start a service
 
-Starts a stopped service.
-
 ```
 PUT /v1/services/:name/start
 ```
 
+Starts a stopped service.
+
 #### Response
 
 Service is started:

Documentation/REST-API/Resources-Session.md

@@ -8,12 +8,13 @@ session is created on a service and each service can have multiple sessions.
 
 ### Get a session
 
-Get a single session. _:id_ must be a valid session ID.
-
 ```
 GET /v1/sessions/:id
 ```
 
+Get a single session. _:id_ must be a valid session ID. The session ID is the
+same that is exposed to the client as the connection ID.
+
 #### Response
 
 `Status: 200 OK`
@@ -55,12 +56,12 @@ GET /v1/sessions/:id
 
 ### Get all sessions
 
-Get all sessions.
-
 ```
 GET /v1/sessions
 ```
 
+Get all sessions.
+
 #### Response
 
 `Status: 200 OK`

Documentation/REST-API/Resources-User.md

@@ -7,13 +7,13 @@ MaxScale's configuration.
 
 ### Get network user
 
-Get a single network user. The The _:name_ in the URI must be a valid network
-user name.
-
 ```
 GET /v1/users/inet/:name
 ```
 
+Get a single network user. The The _:name_ in the URI must be a valid network
+user name.
+
 #### Response
 
 `Status: 200 OK`
@@ -38,12 +38,12 @@ GET /v1/users/inet/:name
 
 ### Get all network users
 
-Get all network users.
-
 ```
 GET /v1/users/inet
 ```
 
+Get all network users.
+
 #### Response
 
 `Status: 200 OK`
@@ -70,13 +70,13 @@ GET /v1/users/inet
 
 ### Get enabled UNIX account
 
-Get a single enabled UNIX account. The The _:name_ in the URI must be a valid
-UNIX account name that has been enabled.
-
 ```
 GET /v1/users/unix/:name
 ```
 
+Get a single enabled UNIX account. The The _:name_ in the URI must be a valid
+UNIX account name that has been enabled.
+
 #### Response
 
 `Status: 200 OK`
@@ -101,12 +101,12 @@ GET /v1/users/unix/:name
 
 ### Get all enabled UNIX accounts
 
-Get all enabled UNIX accounts.
-
 ```
 GET /v1/users/unix
 ```
 
+Get all enabled UNIX accounts.
+
 #### Response
 
 `Status: 200 OK`
@@ -133,13 +133,13 @@ GET /v1/users/unix
 
 ### Get all users
 
-Get all administrative users. This fetches both network users and local UNIX
-accounts.
-
 ```
 GET /v1/users
 ```
 
+Get all administrative users. This fetches both network users and local UNIX
+accounts.
+
 #### Response
 
 `Status: 200 OK`
@@ -176,21 +176,24 @@ GET /v1/users
 
 ### Create a network user
 
-Create a new network user.
-
 ```
 POST /v1/users/inet
 ```
 
-The request body must fulfill the following requirements.
+Create a new network user. The request body must define at least the
+following fields.
 
-- The `/data/id`, `/data/type`, `/data/attributes/account` and
+* `data.id`
-  `/data/attributes/password` fields must be defined.
+  * The username
-- The `/data/id` field defines the name of the account
+
-- The `/data/attributes/password` field defines the password for this user.
+* `data.type`
-- The `/data/attributes/account` field should be set to `admin` for
+  * Type of the object, must be `inet`
-  administrative users and `basic` to read-only users.
+
-- The value of the `/data/type` field must always be `inet`.
+* `data.attributes.password`
+  * The password for this user
+
+* `data.attributes.account`
+  * Set to `admin` for administrative users and `basic` to read-only users
 
 Here is an example request body defining the network user _my-user_ with the
 password _my-password_ that is allowed to execute only read-only operations.
@@ -216,20 +219,21 @@ Status: 204 No Content
 
 ### Enable a UNIX account
 
-This enables an existing UNIX account on the system for administrative
-operations.
-
 ```
 POST /v1/users/unix
 ```
 
-The request body must fulfill the following requirements.
+This enables an existing UNIX account on the system for administrative
+operations. The request body must define at least the following fields.
 
-- The `/data/id`, `/data/type` and `/data/attributes/account` fields must be defined.
+* `data.id`
-- The `/data/id` field defines the name of the account
+  * The username
-- The `/data/attributes/account` field should be set to `admin` for
+
-  administrative users and `basic` to read-only users.
+* `data.type`
-- The value of the `/data/type` field must always be `unix`.
+  * Type of the object, must be `unix`
+
+* `data.attributes.account`
+  * Set to `admin` for administrative users and `basic` to read-only users
 
 Here is an example request body enabling the UNIX account _jdoe_ for read-only operations.
 
@@ -253,12 +257,12 @@ Status: 204 No Content
 
 ### Delete a network user
 
-The _:name_ part of the URI must be a valid user name.
-
 ```
 DELETE /v1/users/inet/:name
 ```
 
+The _:name_ part of the URI must be a valid user name.
+
 #### Response
 
 ```
@@ -267,12 +271,12 @@ Status: 204 No Content
 
 ### Disable a UNIX account
 
-The _:name_ part of the URI must be a valid user name.
-
 ```
 DELETE /v1/users/unix/:name
 ```
 
+The _:name_ part of the URI must be a valid user name.
+
 #### Response
 
 ```