[GitHub] [couchdb-documentation] nickva commented on a change in pull request #404: Add _reshard HTTP API reference documentation

[GitBox <gi...@apache.org>]

nickva commented on a change in pull request #404: Add _reshard HTTP API reference documentation
URL: https://github.com/apache/couchdb-documentation/pull/404#discussion_r271769598
 
 

 ##########
 File path: src/api/server/common.rst
 ##########
 @@ -1675,3 +1675,479 @@ You can verify the change by obtaining a list of UUIDs:
     :>header Content-Type: :mimetype:`image/x-icon`
     :code 200: Request completed successfully
     :code 404: The requested content could not be found
+
+.. _api/server/reshard:
+
+=============
+``/_reshard``
+=============
+
+.. versionadded:: 2.4
+
+.. http:get:: /_reshard
+    :synopsis: Retrieve summary information about resharding on the cluster
+
+    Returns a count of completed, failed, running, stopped, and total jobs
+    along with the state of resharding on the cluster.
+
+    :<header Accept: - :mimetype:`application/json`
+    :>header Content-Type: - :mimetype:`application/json`
+
+    :>json string state: ``stopped`` or ``running``
+    :>json string state_reason: ``null`` or string describing additional
+                                information or reason associated with the state
+    :>json number completed: Count of completed resharding jobs
+    :>json number failed: Count of failed resharding jobs
+    :>json number running: Count of running resharding jobs
+    :>json number stopped: Count of stopped resharding jobs
+    :>json number total: Total count of resharding jobs
+
+    :code 200: Request completed successfully
+    :code 401: CouchDB Server Administrator privileges required
+
+    **Request**:
+
+    .. code-block:: http
+
+        GET /_reshard HTTP/1.1
+        Accept: application/json
+        Host: localhost:5984
+
+    **Response**:
+
+    .. code-block:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        {
+            "completed": 21,
+            "failed": 0,
+            "running": 3,
+            "state": "running",
+            "state_reason": null,
+            "stopped": 0,
+            "total": 24
+        }
+
+.. http:get:: /_reshard/state
+    :synopsis: Retrieve the state of resharding on the cluster
+
+    Returns the resharding state and optional information about the state.
+
+    :<header Accept: - :mimetype:`application/json`
+    :>header Content-Type: - :mimetype:`application/json`
+
+    :>json string state: ``stopped`` or ``running``
+    :>json string state_reason: Additional  information  or  reason  associated
+                                with the state
+
+    :code 200: Request completed successfully
+    :code 401: CouchDB Server Administrator privileges required
+
+    **Request**:
+
+    .. code-block:: http
+
+        GET /_reshard/state HTTP/1.1
+        Accept: application/json
+        Host: localhost:5984
+
+    **Response**:
+
+    .. code-block:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+
+        {
+            "reason": null,
+            "state": "running"
+        }
+
+.. http:put:: /_reshard/state
+    :synopsis: Change resharding state on the cluster
+
+    Change the resharding state on the cluster. The states are
+    ``stopped`` or ``running``. This starts and stops global resharding on all
+    the nodes of the cluster. If there are any running jobs, they
+    will be stopped when the state changes to ``stopped``. When the state
+    changes back to ``running`` those job will continue running.
+
+    :<header Accept: - :mimetype:`application/json`
+    :>header Content-Type: - :mimetype:`application/json`
+
+    :<json string state: ``stopped`` or ``running``
+    :<json string state_reason: Optional string describing additional
+                                information or reason associated with the state
+
+    :>json boolean ok: ``true``
+
+    :code 200: Request completed successfully
+    :code 401: CouchDB Server Administrator privileges required
 
 Review comment:
   It won't apply here because it's getting the state and resharding will have either a stopped or running state. 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services