Skip to content

Commit cc19cb2

Browse files
jeff-allen-mongojeff-allen-mongo
authored
(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
1 parent 53ee0fe commit cc19cb2

File tree

9 files changed

+160
-19
lines changed

9 files changed

+160
-19
lines changed

‎source/includes/api/requests/reverse.sh

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
curl localhost:27182/api/v1/reverse -XPOST --data '{ }'

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
curl localhost:27182/api/v1/start -XPOST
2+
--data '
3+
{
4+
"source": "cluster0",
5+
"destination": "cluster1",
6+
"reversible": true,
7+
"enableUserWriteBlocking": true
8+
} '

‎source/reference/api.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ API Endpoints
1414
/reference/api/pause
1515
/reference/api/resume
1616
/reference/api/commit
17+
/reference/api/reverse

‎source/reference/api/commit.txt

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,9 @@ Before using the ``commit`` endpoint:
3636

3737
``lagTimeSeconds`` indicates the time between the last applied
3838
event and time of the current latest event. When you send a
39-
``commit`` request, {+c2c-product-name+} enters the
40-
``COMMITTING`` state for the amount of seconds reported by
41-
``lagTimeSeconds``, and then transitions to the ``COMMITTED``
42-
state.
39+
``commit`` request, ``mongosync`` enters the ``COMMITTING`` state
40+
for the amount of seconds reported by ``lagTimeSeconds``, and
41+
then transitions to the ``COMMITTED`` state.
4342

4443
When ``lagTimeSeconds`` is ``0``, the source and destination
4544
clusters are in a consistent state.
@@ -113,6 +112,6 @@ Response
113112
Behavior
114113
--------
115114

116-
If the ``commit`` request is successful, {+c2c-product-name+} enters the
115+
If the ``commit`` request is successful, ``mongosync`` enters the
117116
``COMMITTING`` state, then automatically transitions to the
118117
``COMMITTED`` state.

‎source/reference/api/pause.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ Pauses the current synchronization operation.
2222
Requirement
2323
-----------
2424

25-
To use the ``pause`` endpoint, the {+c2c-product-name+} must be in the
26-
``RUNNING`` state.
25+
To use the ``pause`` endpoint, ``mongosync`` must be in the ``RUNNING``
26+
state.
2727

2828
Request
2929
-------
@@ -58,13 +58,13 @@ Response
5858
~~~~~~~~
5959

6060
.. literalinclude:: /includes/api/responses/success.json
61-
:language: shell
61+
:language: json
6262
:copyable: false
6363

6464
Behavior
6565
--------
6666

67-
- If the ``pause`` request is successful, {+c2c-product-name+} enters the
67+
- If the ``pause`` request is successful, ``mongosync`` enters the
6868
``PAUSED`` state.
6969

7070
- If you plan to pause synchronization for an extended period of time,

‎source/reference/api/progress.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,8 @@ Response
5353
Behavior
5454
--------
5555

56-
- When the {+c2c-product-name+} is in the ``IDLE`` state, all output
56+
- When ``mongosync`` is in the ``IDLE`` state, all output
5757
fields except ``state`` and ``canCommit`` are ``null``.
5858

59-
- When the {+c2c-product-name+} is in the ``PAUSED`` state, the
59+
- When ``mongosync`` is in the ``PAUSED`` state, the
6060
``lagTimeSeconds`` field is ``null``.

‎source/reference/api/resume.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@ destination cluster.
2323
Requirement
2424
-----------
2525

26-
To use the ``resume`` endpoint, the {+c2c-product-name+} must be in the
27-
``PAUSED`` state.
26+
To use the ``resume`` endpoint, ``mongosync`` must be in the ``PAUSED``
27+
state.
2828

2929
Request
3030
-------
@@ -65,5 +65,5 @@ Response
6565
Behavior
6666
--------
6767

68-
If the ``resume`` request is successful, {+c2c-product-name+} enters the
68+
If the ``resume`` request is successful, ``mongosync`` enters the
6969
``RUNNING`` state.

‎source/reference/api/reverse.txt

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
.. _c2c-api-reverse:
2+
3+
===========
4+
``reverse``
5+
===========
6+
7+
.. include:: /includes/preview-warning
8+
9+
.. default-domain:: mongodb
10+
11+
.. contents:: On this page
12+
:local:
13+
:backlinks: none
14+
:depth: 2
15+
:class: singlecol
16+
17+
Description
18+
-----------
19+
20+
Reverses the direction of a committed sync operation.
21+
22+
For example:
23+
24+
- You have a ``COMMITTED`` sync operation.
25+
26+
- ``cluster0`` is the source and ``cluster1`` is the destination.
27+
28+
- After the sync operation is ``COMMITTED``, new writes occur only on
29+
the destination cluster. The source cluster will not accept new
30+
writes.
31+
32+
In this scenario, you can use the ``reverse`` endpoint to sync writes
33+
from ``cluster1`` to ``cluster0``.
34+
35+
Requirements
36+
------------
37+
38+
To use the ``reverse`` endpoint:
39+
40+
- You must have started your original sync operation with the
41+
``reversible`` and ``enableUserWriteBlocking`` options set to
42+
``true``.
43+
44+
- ``mongosync`` must be in the ``COMMITTED`` state.
45+
46+
Request
47+
-------
48+
49+
.. code-block:: http
50+
:copyable: false
51+
52+
POST /api/v1/reverse
53+
54+
Request Body Parameters
55+
~~~~~~~~~~~~~~~~~~~~~~~
56+
57+
.. include:: includes/api/facts/no-body-parameters.rst
58+
59+
Response
60+
--------
61+
62+
.. include:: /includes/api/tables/basic-response.rst
63+
64+
Example
65+
-------
66+
67+
The following example reverses the direction of a committed sync operation.
68+
69+
Request
70+
~~~~~~~
71+
72+
.. literalinclude:: /includes/api/requests/reverse.sh
73+
:language: shell
74+
75+
Response
76+
~~~~~~~~
77+
78+
.. literalinclude:: /includes/api/responses/success.json
79+
:language: json
80+
:copyable: false
81+
82+
Behavior
83+
--------
84+
85+
If the ``reverse`` request is successful, ``mongosync`` enters the
86+
``RUNNING`` state. The synchronization continues in the reverse
87+
direction from the original sync job. You do not need to restart the
88+
entire sync process to copy the original data.
89+
90+
To view the mapping direction for the synchronization of the source and
91+
destination clusters, use the :ref:`progress <c2c-api-progress>`
92+
endpoint and check the ``directionMapping`` object.

‎source/reference/api/start.txt

Lines changed: 45 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ Starts the synchronization between a source and destination cluster.
2222
Requirement
2323
-----------
2424

25-
To use the ``start`` endpoint, the {+c2c-product-name+} must be in the
26-
``IDLE`` state.
25+
To use the ``start`` endpoint, ``mongosync`` must be in the ``IDLE``
26+
state.
2727

2828
Request
2929
-------
@@ -56,13 +56,33 @@ Request Body Parameters
5656
- Required
5757
- Name of the destination cluster.
5858

59+
* - ``reversible``
60+
- boolean
61+
- Optional
62+
- If set to ``true``, enables the synchronization operation to be
63+
reversed. For more information, see the :ref:`reverse
64+
<c2c-api-reverse>` endpoint.
65+
66+
Default value is ``false``.
67+
68+
* - ``enableUserWriteBlocking``
69+
- boolean
70+
- Optional
71+
- If set to ``true``, blocks writes on the destination cluster
72+
while the synchronization is in progress. After the
73+
synchronization is committed to the destination cluster, the
74+
original source cluster blocks writes and the destination cluster
75+
accepts writes.
76+
77+
Default value is ``false``.
78+
5979
Response
6080
--------
6181

6282
.. include:: /includes/api/tables/basic-response.rst
6383

64-
Example
65-
-------
84+
Example 1 - Start a Standard Sync Job
85+
-------------------------------------
6686

6787
The following example starts a synchronization job where ``cluster0`` is
6888
the source and ``cluster1`` is the destination.
@@ -76,12 +96,32 @@ Request
7696
Response
7797
~~~~~~~~
7898

99+
.. literalinclude:: /includes/api/responses/success.json
100+
:language: json
101+
:copyable: false
102+
103+
Example 2 - Start a Reversible Sync Job
104+
---------------------------------------
105+
106+
The following example starts a synchronization job where ``cluster0`` is
107+
the source and ``cluster1`` is the destination. The ``reversible`` and
108+
``enableUserWriteBlocking`` fields allow the sync to be reversed.
109+
110+
Request
111+
~~~~~~~
112+
113+
.. literalinclude:: /includes/api/requests/start-reversible.sh
114+
:language: shell
115+
116+
Response
117+
~~~~~~~~
118+
79119
.. literalinclude:: /includes/api/responses/success.json
80120
:language: json
81121
:copyable: false
82122

83123
Behavior
84124
--------
85125

86-
If the ``start`` request is successful, {+c2c-product-name+} enters the
126+
If the ``start`` request is successful, ``mongosync`` enters the
87127
``RUNNING`` state.

0 commit comments

Comments
 (0)