(DOCSP-22949): pause endpoint (#12)

* (DOCSP-22949): pause endpoint

* update example

* fix example links

* wording and reformatting

* add link to faq

* wording

* typo

Author: jeff-allen-mongo

source/faq.txt

@@ -18,6 +18,8 @@ When ``mongosync`` runs on its own hardware, it does not have to use
 the same operation system (OS) as the source or destination clusters it
 is connecting.
 
+.. _c2c-faq-increase-oplog:
+
 Should I increase the size of the oplog in the source cluster?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -88,4 +90,3 @@ have more than 2 non-arbiter nodes and you must sync from a non-arbiter
 node. Use the source cluster's connection string to specify a
 :ref:`read preference <mongodb-uri>` for a non-arbiter, data-bearing
 node. 
-

source/includes/api/requests/pause.sh

@@ -0,0 +1 @@
+curl localhost:27182/api/v1/pause -XPOST --data '{ }'

source/includes/api/tables/basic-response.rst

@@ -0,0 +1,22 @@
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 20 14 66
+
+   * - Name
+     - Type
+     - Description
+
+   * - ``success``
+     - boolean
+     - When the request is successful, this value is ``true``.
+
+   * - ``error``
+     - string
+     - If an error occurred, indicates the name of the error. This field
+       is omitted from the response when ``success`` is ``true``.
+
+   * - ``errorDescription``
+     - string
+     - Detailed description of the error that occurred. This field is
+       omitted from the response when ``success`` is ``true``.

source/reference/api.txt

@@ -9,4 +9,5 @@ API
 .. toctree::
    :titlesonly: 
 
+   /reference/api/pause
    /reference/api/start

source/reference/api/pause.txt

@@ -0,0 +1,69 @@
+.. _c2c-api-pause:
+
+=========
+``pause``
+=========
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Description
+-----------
+
+Pauses the current synchronization operation. 
+
+Requirement
+-----------
+
+To use the ``pause`` endpoint, the {+c2c-product-name+} must be in the
+``RUNNING`` state.
+
+Request
+-------
+
+.. code-block:: http
+
+   POST /api/v1/pause 
+
+Request Body Parameters
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This endpoint does not use HTTP request body parameters.
+
+Response
+--------
+
+.. include:: /includes/api/tables/basic-response.rst
+
+Example
+-------
+
+The following example pauses the current synchronization operation.
+
+Request
+~~~~~~~
+
+.. literalinclude:: /includes/api/requests/pause.sh
+   :language: shell
+
+Response
+~~~~~~~~
+
+.. literalinclude:: /includes/api/responses/success.sh
+   :language: shell
+
+Behavior
+--------
+
+- If the ``pause`` request is successful, {+c2c-product-name+} enters the
+  ``PAUSED`` state.
+
+- If you plan to pause synchronization for an extended period of time,
+  increase the size of the replica set :term:`oplog` in the source
+  cluster. To learn more, see :ref:`Frequently Asked Questions
+  <c2c-faq-increase-oplog>`. 

source/reference/api/start.txt

@@ -17,6 +17,12 @@ Description
 
 Starts the synchronization between a source and destination cluster.
 
+Requirement
+-----------
+
+To use the ``start`` endpoint, the {+c2c-product-name+} must be in the
+``IDLE`` state.
+
 Request
 -------
 
@@ -50,28 +56,7 @@ Request Body Parameters
 Response
 --------
 
-.. list-table::
-   :header-rows: 1
-   :stub-columns: 1
-   :widths: 20 14 66
-
-   * - Name
-     - Type
-     - Description
-
-   * - ``success``
-     - boolean
-     - When the request is successful, this value is ``true``.
-
-   * - ``error``
-     - string
-     - If an error occurred, indicates the name of the error. This field
-       is omitted from the response when ``success`` is ``true``.
-
-   * - ``errorDescription``
-     - string
-     - Detailed description of the error that occurred. This field is
-       omitted from the response when ``success`` is ``true``.
+.. include:: /includes/api/tables/basic-response.rst
 
 Example
 -------
@@ -94,5 +79,5 @@ Response
 Behavior
 --------
 
-If {+c2c-product-name+} is in a state other than ``IDLE``, the request
-fails.
+If the ``start`` request is successful, {+c2c-product-name+} enters the
+``RUNNING`` state.