Skip to content

Commit 2dd80a1

Browse files
jeff-allen-mongojeff-allen-mongo
authored
(DOCSP-22951,DOCSP-22952): commit and progress endpoints (#15)
* (DOCSP-22951,DOCSP-22952): commit and progress endpoints * wording * formatting * formatting * change highlighting * tweaks and improvements * wording * change type of responses from .sh to .json * clarification * fix extensions * final fix * wording * formatting * add empty object clarification for body element * reorder API endpoints * missing word * fix success example * change output language * code review suggestions * formatting * tweaks for lagTimeSeconds * rewording * missing period * formatting * remove accidental states updates
1 parent 04b4c6c commit 2dd80a1

File tree

13 files changed

+267
-9
lines changed

13 files changed

+267
-9
lines changed

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

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

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
curl localhost:27182/api/v1/progress -XGET

‎source/includes/api/responses/progress.json

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"progress":
3+
{
4+
"state":"RUNNING",
5+
"canCommit":true,
6+
"info":"change event application",
7+
"lagTimeSeconds":0,
8+
"collectionCopy":
9+
{
10+
"estimatedTotalBytes":694,
11+
"estimatedCopiedBytes":694
12+
},
13+
"directionMapping":
14+
{
15+
"Source":"cluster0: localhost:27017",
16+
"Destination":"cluster1: localhost:27018"
17+
}
18+
}
19+
}

‎source/includes/api/responses/success.sh renamed to ‎source/includes/api/responses/success.json

File renamed without changes.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
:stub-columns: 1
44
:widths: 20 14 66
55

6-
* - Name
6+
* - Field
77
- Type
88
- Description
99

‎source/includes/api/tables/progress-response.rst

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
.. list-table::
2+
:header-rows: 1
3+
:stub-columns: 1
4+
:widths: 20 14 66
5+
6+
* - Field
7+
- Type
8+
- Description
9+
10+
* - ``state``
11+
- string
12+
- The current state of {+c2c-product-name+}.
13+
14+
* - ``canCommit``
15+
- boolean
16+
- If ``true``, indicates that a :ref:`commit <c2c-api-commit>`
17+
request will succeed. This also means that the initial sync has
18+
completed and is applying change events.
19+
20+
* - ``info``
21+
- string
22+
- Provides extra information on the synchronization progress.
23+
Possible ``info`` values include:
24+
25+
- ``"collection copy"``
26+
- ``"change event application"``
27+
- ``"waiting for commit to complete"``
28+
- ``"commit completed"``
29+
30+
* - ``lagTimeSeconds``
31+
- integer
32+
- Time in seconds between the last applied event and time of the
33+
current latest event.
34+
35+
* - ``collectionCopy``
36+
- object
37+
- Describes the total amount of data being copied and the
38+
amount that has already been copied to the destination cluster.
39+
40+
* - ``collectionCopy.estimatedTotalBytes``
41+
- integer
42+
- Estimated total number of bytes to be copied.
43+
44+
* - ``collectionCopy.estimatedCopiedBytes``
45+
- integer
46+
- Estimated number of bytes which have been copied to the
47+
destination cluster.
48+
49+
* - ``directionMapping``
50+
- object
51+
- Describes the mapping direction for the synchronization, namely
52+
the source and destination clusters.
53+
54+
* - ``directionMapping.Source``
55+
- string
56+
- Source cluster. Returned in the form
57+
``<cluster name>: <host>:<port>``.
58+
59+
* - ``directionMapping.Destination``
60+
- string
61+
- Destination cluster. Returned in the form
62+
``<cluster name>: <host>:<port>``.
63+

‎source/reference.txt

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,3 @@ Reference
99

1010
/reference/mongosync
1111
/reference/api
12-

‎source/reference/api.txt

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,15 @@
22

33
.. default-domain:: mongodb
44

5-
===
6-
API
7-
===
5+
=============
6+
API Endpoints
7+
=============
88

99
.. toctree::
1010
:titlesonly:
1111

12+
/reference/api/start
13+
/reference/api/progress
1214
/reference/api/pause
1315
/reference/api/resume
14-
/reference/api/start
16+
/reference/api/commit

‎source/reference/api/commit.txt

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
.. _c2c-api-commit:
2+
3+
==========
4+
``commit``
5+
==========
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
Description
16+
-----------
17+
18+
Commits the synchronization operation to the destination cluster.
19+
20+
Requirements
21+
------------
22+
23+
Before using the ``commit`` endpoint:
24+
25+
- Stop your application. This ensures that no additional writes occur on
26+
the source cluster.
27+
28+
- Use the :ref:`progress <c2c-api-progress>` endpoint to confirm the
29+
following values:
30+
31+
- ``state: "RUNNING"``
32+
- ``canCommit: true``
33+
- ``lagTimeSeconds`` is near ``0`` (*Recommended, but not required*)
34+
35+
.. note:: lagTimeSeconds
36+
37+
``lagTimeSeconds`` indicates the time between the last applied
38+
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.
43+
44+
When ``lagTimeSeconds`` is ``0``, the source and destination
45+
clusters are in a consistent state.
46+
47+
Request
48+
-------
49+
50+
.. code-block:: http
51+
52+
POST /api/v1/commit
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 commits the synchronization operation to the
68+
destination cluster.
69+
70+
Confirm that the Synchronization is Ready
71+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72+
73+
Before sending a request to the ``commit`` endpoint, use the
74+
:ref:`progress <c2c-api-progress>` endpoint to confirm that the
75+
synchronization is ready to be committed.
76+
77+
Request
78+
```````
79+
80+
.. literalinclude:: /includes/api/requests/progress.sh
81+
:language: shell
82+
83+
Response
84+
````````
85+
86+
.. literalinclude:: /includes/api/responses/progress.json
87+
:language: shell
88+
:emphasize-lines: 5
89+
90+
The ``progress`` endpoint returned ``"canCommit":true``, which means
91+
that the ``commit`` request can run successfully.
92+
93+
Send the Commit Request
94+
~~~~~~~~~~~~~~~~~~~~~~~
95+
96+
The following command sends a request to the ``commit`` endpoint:
97+
98+
Request
99+
```````
100+
101+
.. literalinclude:: /includes/api/requests/commit.sh
102+
:language: shell
103+
104+
Response
105+
````````
106+
107+
.. literalinclude:: /includes/api/responses/success.json
108+
:language: json
109+
110+
Behavior
111+
--------
112+
113+
If the ``commit`` request is successful, {+c2c-product-name+} enters the
114+
``COMMITTING`` state, then automatically transitions to the
115+
``COMMITTED`` state.

‎source/reference/api/pause.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Request
5454
Response
5555
~~~~~~~~
5656

57-
.. literalinclude:: /includes/api/responses/success.sh
57+
.. literalinclude:: /includes/api/responses/success.json
5858
:language: shell
5959

6060
Behavior

0 commit comments

Comments
 (0)