(DOCSP-15528): Add Stable API options to the Mongo() Constructor (#2211) (#2224)

* Add API options to Mongo constructor

* copy review feedback

* copy review feedback 2

* tech review feedback

Author: davidhou17

source/includes/stable-api-options.rst

@@ -0,0 +1,30 @@
+.. list-table::
+   :widths: 20,10,70
+   :header-rows: 1
+
+   * - |param|
+     - Type
+     - Description
+
+   * - |apiVersion|
+     - string
+     - Specifies the API Version. ``"1"`` is
+       currently the only supported version.
+          
+   * - |strict|
+     - boolean 
+     - If ``true``, using a command that is not
+       part of the declared API version returns an
+       :ref:`APIStrictError <api-strict-resp>` error. If you specify
+       |strict|, you must also specify |apiVersion|.  
+
+       If not specified, defaults to ``false``. 
+
+   * - |deprecation|
+     - boolean
+     - If ``true``, using a command or behavior that is deprecated 
+       in the specified API version returns an 
+       :ref:`APIDeprecationError <api-deprecation-resp>`. If you specify
+       |deprecation|, you must also specify |apiVersion|.
+
+       If not specified, defaults to ``false``. 

source/reference/method/Mongo.txt

@@ -7,15 +7,15 @@ Mongo()
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Description
 -----------
 
 .. versionchanged:: 4.2
 
-.. method:: Mongo(host, {+auto-encrypt-options+})
+.. method:: Mongo(host, {+auto-encrypt-options+}, api)
 
    JavaScript constructor to instantiate a database connection from
    :binary:`~bin.mongosh` or from a JavaScript file.
@@ -36,21 +36,19 @@ Description
 
         - string
 
-        - Optional. The host, either in the form of ``<host>`` or
+        - *Optional*. The host, either in the form of ``<host>`` or
           ``<host><:port>``.
 
           If omitted, :method:`Mongo` instantiates a connection to the
           localhost interface on the default port ``27017``.
 
       * - ``{+auto-encrypt-options+}``
 
-        - Document
+        - document
 
-        - *Optional*
-
-          .. versionadded:: 4.2
-
-          Configuration parameters for enabling
+        - .. versionadded:: 4.2
+          
+          *Optional*. Configuration parameters for enabling
           :ref:`manual-csfle-feature`.
 
           ``{+auto-encrypt-options+}`` overrides the
@@ -59,14 +57,22 @@ Description
           inherits the client-side field level encryption configuration
           of the current database connection.
 
-          For documentation of usage and syntax, see
-          :ref:`{+auto-encrypt-options+}`.
+          See :ref:`{+auto-encrypt-options+}` for usage and syntax 
+          details.
+
+      * - ``api``
+
+        - document
+
+        - *Optional*. Configuration options for enabling the       
+          :ref:`Stable API <stable-api>`.
+
+          See :ref:`mongo-api-options` for usage and syntax details.
 
 .. seealso::
 
    :method:`Mongo.getDB()` and :method:`db.getMongo()`
 
-
 .. _{+auto-encrypt-options+}:
 
 ``{+title-auto-encrypt-options+}``
@@ -261,9 +267,32 @@ following parameters:
        indexed fields without the ``crypt_shared`` library. For details,
        see :ref:`qe-reference-mongo-client`.
 
-Example
+
+.. _mongo-api-options:
+
+``api``
 -------
 
+The ``api`` parameter specifies configuration options for the 
+:ref:`Stable API <stable-api>`. You can enable or disable optional
+behavior using the following options:
+
+.. include:: /includes/stable-api-options.rst
+  
+.. |param| replace:: Option
+.. |apiVersion| replace:: ``version``
+.. |strict| replace:: ``strict``
+.. |deprecation| replace:: ``deprecationErrors``
+
+The ``api`` parameter has the following syntax:
+
+.. code-block:: javascript
+
+   { api: { version: <string>, strict: <boolean>, deprecationErrors: <boolean> } }
+
+Examples
+--------
+
 Connect to a MongoDB Cluster
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -284,8 +313,8 @@ Issue operations against the ``cluster`` object to interact with the
 
 .. _mongo-connection-client-side-encryption-enabled:
 
-Connect to a MongoDB Cluster with Client-Side Encryption Enabled
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Connect to a Cluster with Client-Side Encryption Enabled
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Configuring client-side field level encryption for a :ref:`locally
 managed key <field-level-encryption-local-kms>` requires specifying a
@@ -345,8 +374,8 @@ a complete list of client-side field level encryption methods.
 
 .. _mongo-connection-automatic-client-side-encryption-enabled:
 
-Connect to a MongoDB Cluster with Automatic Client-Side Encryption Enabled
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Connect to a Cluster with Automatic Client-Side Encryption Enabled
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Configuring client-side field level encryption for a :ref:`locally
 managed key <field-level-encryption-local-kms>` requires specifying a
@@ -431,3 +460,23 @@ the specified data encryption key can decrypt the field.
 
 See :doc:`/reference/method/js-client-side-field-level-encryption` for
 a complete list of client-side field level encryption methods.
+
+Connect to a Cluster with the Stable API Enabled
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following operation creates a new connection object from within a
+:binary:`~bin.mongosh` session. The :ref:`mongo-api-options` option 
+enables Stable API V1 and specifies that you cannot 
+run deprecated command or commands outside of the Stable API.
+
+.. code-block:: javascript
+
+   cluster = Mongo(
+     "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster", 
+      null, 
+      { api: { version: "1", strict: true, deprecationErrors: true } }
+   )
+
+To interact with the ``mymongo.example.net:27017`` cluster, issue
+operations against the ``cluster`` object. For a full list of Stable API
+commands, see :ref:`<api-v1-command-list>`.

source/reference/stable-api.txt

@@ -534,52 +534,16 @@ your application's MongoDB driver connection code. Check the MongoDB
 driver documentation for the driver you use in your application for 
 more information:
 
-.. list-table::
-   :widths: 30,30,40
-   :header-rows: 1
-
-   * - Parameter
-
-     - Type
-
-     - Description
-
-   * - :ref:`apiVersion <api-version-desc>`
-
-     - string
-
-     - .. _api-version-desc:
-       
-       API Version. ``"1"`` is currently the only supported API Version.
-       
-       See :ref:`APIVersionError <api-vers-resp>`.
-   
-   * - :ref:`apiStrict <api-strict-desc>`
+.. _api-version-desc:
+.. _api-strict-desc: 
+.. _api-depr-desc:
 
-     - boolean 
-
-     - .. _api-strict-desc: 
-     
-       If ``true``, your application can only use commands defined for 
-       your specified :ref:`apiVersion <api-version-desc>`.     
-
-       If not specified, defaults to ``false``. 
-
-       See :ref:`APIStrictError <api-strict-resp>`.
-
-   * - :ref:`apiDeprecationErrors <api-depr-desc>`
-
-     - boolean
-
-     - .. _api-depr-desc:
-       
-       If ``true``, your application errors if it invokes a command or 
-       behavior that is deprecated in the specified 
-       :ref:`apiVersion <api-version-desc>`.
-
-       If not specified, defaults to ``false``. 
-       
-       See :ref:`APIDeprecationError <api-deprecation-resp>`.
+.. include:: /includes/stable-api-options.rst
+  
+.. |param| replace:: Parameter
+.. |apiVersion| replace:: :ref:`apiVersion <api-version-desc>`
+.. |strict| replace:: :ref:`apiStrict <api-strict-desc>`
+.. |deprecation| replace:: :ref:`apiDeprecationErrors <api-depr-desc>`
 
 
 Behavior