(DOCSP-23028): reverse endpoint (#27)

* WIP

* (DOCSP-23028): reverse endpoint

* wording

* add missing start endpoint fields

* active voice

* address Alan's feedback

* address Dave's feedback

* formatting

* address remaining feedback

Author: jeff-allen-mongo

source/includes/api/requests/reverse.sh

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

source/includes/api/requests/start-reversible.sh

@@ -0,0 +1,8 @@
+curl localhost:27182/api/v1/start -XPOST
+--data '
+   {
+      "source": "cluster0",
+      "destination": "cluster1",
+      "reversible": true,
+      "enableUserWriteBlocking": true
+   } '

source/reference/api.txt

@@ -14,3 +14,4 @@ API Endpoints
    /reference/api/pause
    /reference/api/resume
    /reference/api/commit
+   /reference/api/reverse

source/reference/api/commit.txt

@@ -36,10 +36,9 @@ Before using the ``commit`` endpoint:
 
        ``lagTimeSeconds`` indicates the time between the last applied
        event and time of the current latest event. When you send a
-       ``commit`` request, {+c2c-product-name+} enters the
-       ``COMMITTING`` state for the amount of seconds reported by
-       ``lagTimeSeconds``, and then transitions to the ``COMMITTED``
-       state.
+       ``commit`` request, ``mongosync`` enters the ``COMMITTING`` state
+       for the amount of seconds reported by ``lagTimeSeconds``, and
+       then transitions to the ``COMMITTED`` state.
 
        When ``lagTimeSeconds`` is ``0``, the source and destination
        clusters are in a consistent state.
@@ -113,6 +112,6 @@ Response
 Behavior
 --------
 
-If the ``commit`` request is successful, {+c2c-product-name+} enters the
+If the ``commit`` request is successful, ``mongosync`` enters the
 ``COMMITTING`` state, then automatically transitions to the
 ``COMMITTED`` state.

source/reference/api/pause.txt

@@ -22,8 +22,8 @@ Pauses the current synchronization operation.
 Requirement
 -----------
 
-To use the ``pause`` endpoint, the {+c2c-product-name+} must be in the
-``RUNNING`` state.
+To use the ``pause`` endpoint, ``mongosync`` must be in the ``RUNNING``
+state.
 
 Request
 -------
@@ -58,13 +58,13 @@ Response
 ~~~~~~~~
 
 .. literalinclude:: /includes/api/responses/success.json
-   :language: shell
+   :language: json
    :copyable: false
 
 Behavior
 --------
 
-- If the ``pause`` request is successful, {+c2c-product-name+} enters the
+- If the ``pause`` request is successful, ``mongosync`` enters the
   ``PAUSED`` state.
 
 - If you plan to pause synchronization for an extended period of time,

source/reference/api/progress.txt

@@ -53,8 +53,8 @@ Response
 Behavior
 --------
 
-- When the {+c2c-product-name+} is in the ``IDLE`` state, all output
+- When ``mongosync`` is in the ``IDLE`` state, all output
   fields except ``state`` and ``canCommit`` are ``null``.
 
-- When the {+c2c-product-name+} is in the ``PAUSED`` state, the
+- When ``mongosync`` is in the ``PAUSED`` state, the
   ``lagTimeSeconds`` field is ``null``.

source/reference/api/resume.txt

@@ -23,8 +23,8 @@ destination cluster.
 Requirement
 -----------
 
-To use the ``resume`` endpoint, the {+c2c-product-name+} must be in the
-``PAUSED`` state.
+To use the ``resume`` endpoint, ``mongosync`` must be in the ``PAUSED``
+state.
 
 Request
 -------
@@ -65,5 +65,5 @@ Response
 Behavior
 --------
 
-If the ``resume`` request is successful, {+c2c-product-name+} enters the
+If the ``resume`` request is successful, ``mongosync`` enters the
 ``RUNNING`` state.

source/reference/api/reverse.txt

@@ -0,0 +1,92 @@
+.. _c2c-api-reverse:
+
+===========
+``reverse``
+===========
+
+.. include:: /includes/preview-warning
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Description
+-----------
+
+Reverses the direction of a committed sync operation.
+
+For example:
+
+- You have a ``COMMITTED`` sync operation.
+
+- ``cluster0`` is the source and ``cluster1`` is the destination.
+
+- After the sync operation is ``COMMITTED``, new writes occur only on
+  the destination cluster. The source cluster will not accept new
+  writes.
+
+In this scenario, you can use the ``reverse`` endpoint to sync writes
+from ``cluster1`` to ``cluster0``.
+
+Requirements
+------------
+
+To use the ``reverse`` endpoint:
+
+- You must have started your original sync operation with the
+  ``reversible`` and ``enableUserWriteBlocking`` options set to
+  ``true``.
+
+- ``mongosync`` must be in the ``COMMITTED`` state.
+
+Request
+-------
+
+.. code-block:: http
+   :copyable: false
+
+   POST /api/v1/reverse 
+
+Request Body Parameters
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: includes/api/facts/no-body-parameters.rst
+
+Response
+--------
+
+.. include:: /includes/api/tables/basic-response.rst
+
+Example
+-------
+
+The following example reverses the direction of a committed sync operation.
+
+Request
+~~~~~~~
+
+.. literalinclude:: /includes/api/requests/reverse.sh
+   :language: shell
+
+Response
+~~~~~~~~
+
+.. literalinclude:: /includes/api/responses/success.json
+   :language: json
+   :copyable: false
+
+Behavior
+--------
+
+If the ``reverse`` request is successful, ``mongosync`` enters the
+``RUNNING`` state. The synchronization continues in the reverse
+direction from the original sync job. You do not need to restart the
+entire sync process to copy the original data.
+
+To view the mapping direction for the synchronization of the source and
+destination clusters, use the :ref:`progress <c2c-api-progress>`
+endpoint and check the ``directionMapping`` object.

source/reference/api/start.txt

@@ -22,8 +22,8 @@ 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.
+To use the ``start`` endpoint, ``mongosync`` must be in the ``IDLE``
+state.
 
 Request
 -------
@@ -56,13 +56,33 @@ Request Body Parameters
      - Required
      - Name of the destination cluster.
 
+   * - ``reversible``
+     - boolean
+     - Optional
+     - If set to ``true``, enables the synchronization operation to be
+       reversed. For more information, see the :ref:`reverse
+       <c2c-api-reverse>` endpoint.
+       
+       Default value is ``false``.
+
+   * - ``enableUserWriteBlocking``
+     - boolean
+     - Optional
+     - If set to ``true``, blocks writes on the destination cluster
+       while the synchronization is in progress. After the
+       synchronization is committed to the destination cluster, the
+       original source cluster blocks writes and the destination cluster
+       accepts writes.
+
+       Default value is ``false``.
+
 Response
 --------
 
 .. include:: /includes/api/tables/basic-response.rst
 
-Example
--------
+Example 1 - Start a Standard Sync Job
+-------------------------------------
 
 The following example starts a synchronization job where ``cluster0`` is
 the source and ``cluster1`` is the destination.
@@ -76,12 +96,32 @@ Request
 Response
 ~~~~~~~~
 
+.. literalinclude:: /includes/api/responses/success.json
+   :language: json
+   :copyable: false
+
+Example 2 - Start a Reversible Sync Job
+---------------------------------------
+
+The following example starts a synchronization job where ``cluster0`` is
+the source and ``cluster1`` is the destination. The ``reversible`` and
+``enableUserWriteBlocking`` fields allow the sync to be reversed.
+
+Request
+~~~~~~~
+
+.. literalinclude:: /includes/api/requests/start-reversible.sh
+   :language: shell
+
+Response
+~~~~~~~~
+
 .. literalinclude:: /includes/api/responses/success.json
    :language: json
    :copyable: false
 
 Behavior
 --------
 
-If the ``start`` request is successful, {+c2c-product-name+} enters the
+If the ``start`` request is successful, ``mongosync`` enters the
 ``RUNNING`` state.