Problem: Docs for BEP#3 implementation not updated (#2123)

* Problem: Docs for BEP#3 implementation not updated

Solutions: Update docs for #2070 and #2106

* Problem: 'Validator update' docs language not clear

Solution: Re-write the documentation which explains when validators are updated

* Problem: Typos and BEP reference missing

Solution: Fix typos and add BEP reference

docs/server/source/http-client-server-api.rst

@@ -515,6 +515,50 @@ Transaction Metadata
                     text search.
 
 
+Validators
+--------------------
+
+.. http:get:: /api/v1/validators
+
+    Return the local validators set of a given node.
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+    GET /api/v1/validators HTTP/1.1
+    Host: example.com
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+    HTTP/1.1 200 OK
+    Content-type: application/json
+
+    [
+        {
+            "pub_key": {
+                   "data":"4E2685D9016126864733225BE00F005515200727FBAB1312FC78C8B76831255A",
+                   "type":"ed25519"
+            },
+            "power": 10
+        },
+        {
+             "pub_key": {
+                   "data":"608D839D7100466D6BA6BE79C320F8B81DE93CFAA58CF9768CF921C6371F2553",
+                   "type":"ed25519"
+             },
+             "power": 5
+        }
+    ]
+
+
+   :resheader Content-Type: ``application/json``
+
+   :statuscode 200: The query was executed successfully and validators set was returned.
+
+
 Advanced Usage
 --------------------------------
 

docs/server/source/server-reference/bigchaindb-cli.md

@@ -73,3 +73,25 @@ section of Python's documentation.
 For a more fine-grained control over the logging configuration you can use the
 configuration file as documented under
 [Configuration Settings](configuration.html).
+
+
+## bigchaindb upsert-validator
+_[BEP#3](https://github.com/bigchaindb/BEPs/tree/master/3)_
+
+Add/Update/Remove a validator from the validaors set of the local node. Below is the command line syntax,
+
+```bash
+$ bigchaindb upsert-validator PUBLIC_KEY_OF_VALIDATOR POWER
+```
+
+Example usage,
+
+```bash
+$ bigchaindb upsert-validator B0E42D2589A455EAD339A035D6CE1C8C3E25863F268120AA0162AD7D003A4014 10
+```
+
+If the command is returns without any error then a request to update the validator set has been successfully submitted. So, even if the command has been successfully executed it doesn't imply that the validator set has been updated. In order to check whether the change has been applied, the node operator can execute `curl http://node_ip:9985/api/v1/validators` which will list the current validators set. Refer to the [validators](/http-client-server-api.html#validators) section of the HTTP API docs for more detail.
+
+Note:
+- When `POWER`is set to `0` then the validator will be removed from the validator set.
+- Upsert requests are handled once per block i.e. the validators set is updated once a new block is committed. So, the node operator is not allowed to submit a new upsert request until the current request has been processed. Furthermore, if Tendermint is started with `--consensus.create_empty_blocks=false`, and there are no new incoming transactions then the validators set update is delayed until any new transactions are received and a new block can be committed.