diff --git a/config/redirects b/config/redirects index 36d1310db..b0d5030e1 100644 --- a/config/redirects +++ b/config/redirects @@ -1,6 +1,8 @@ define: prefix drivers/node define: base https://docs.mongodb.com/${prefix} -define: versions v3.6 master +define: versions v3.6 v3.7 v4.0 v4.1 v4.2 v4.3 master raw: ${prefix}/ -> ${base}/current/ raw: ${prefix}/stable -> ${base}/current/ + +[*-master]: ${prefix}/${version}/fundamentals/versioned-api/ -> ${prefix}/${version}/fundamentals/stable-api/ diff --git a/snooty.toml b/snooty.toml index fd311b480..9840469bb 100644 --- a/snooty.toml +++ b/snooty.toml @@ -13,3 +13,4 @@ mongosh = "``mongosh``" driver = "node" driver-long = "MongoDB Node.js driver" driver-short = "Node.js driver" +stable-api = "Stable API" diff --git a/source/code-snippets/versioned-api/basic.js b/source/code-snippets/stable-api/basic.js similarity index 100% rename from source/code-snippets/versioned-api/basic.js rename to source/code-snippets/stable-api/basic.js diff --git a/source/code-snippets/versioned-api/options.js b/source/code-snippets/stable-api/options.js similarity index 100% rename from source/code-snippets/versioned-api/options.js rename to source/code-snippets/stable-api/options.js diff --git a/source/fundamentals.txt b/source/fundamentals.txt index 04e652175..edbb5fa24 100644 --- a/source/fundamentals.txt +++ b/source/fundamentals.txt @@ -7,7 +7,7 @@ Fundamentals .. toctree:: /fundamentals/connection - /fundamentals/versioned-api + /fundamentals/stable-api /fundamentals/authentication /fundamentals/crud /fundamentals/promises diff --git a/source/fundamentals/connection.txt b/source/fundamentals/connection.txt index 78a5c37a0..fe1b7fc49 100644 --- a/source/fundamentals/connection.txt +++ b/source/fundamentals/connection.txt @@ -265,7 +265,7 @@ URI to specify the behavior of the client. - string *or* enum - ``null`` - Specifies the API version that operations must conform to. See the - MongoDB manual entry on :manual:`Versioned API ` + MongoDB manual entry on :manual:`Stable API ` for more information. * - **srvMaxHosts** diff --git a/source/fundamentals/versioned-api.txt b/source/fundamentals/stable-api.txt similarity index 57% rename from source/fundamentals/versioned-api.txt rename to source/fundamentals/stable-api.txt index b85391885..5a9e09bb2 100644 --- a/source/fundamentals/versioned-api.txt +++ b/source/fundamentals/stable-api.txt @@ -1,6 +1,8 @@ -============= -Versioned API -============= +.. _nodejs-stable-api: + +============== +{+stable-api+} +============== .. default-domain:: mongodb @@ -12,60 +14,62 @@ Versioned API .. note:: - The Versioned API feature requires MongoDB Server 5.0 or later. + The {+stable-api+} feature requires MongoDB Server 5.0 or later. - You should only use the Versioned API feature if all the MongoDB + You should only use the {+stable-api+} feature if all the MongoDB servers you are connecting to support this feature. Overview -------- -In this guide, you can learn how to specify the **Versioned API** when connecting to -a MongoDB instance or replica set. You can use the Versioned API feature to -force the server to run operations with behavior compatible with the -specified **API version**. An API version defines the expected behavior of the -operations it covers and the format of server responses. If you change to -a different API version, the operations are not guaranteed to be -compatible and the server responses are not guaranteed to be similar. +In this guide, you can learn how to specify the **{+stable-api+}** when +connecting to a MongoDB instance or replica set. You can use the +{+stable-api+} feature to force the server to run operations with behavior +compatible with the specified **API version**. An API version defines the +expected behavior of the operations it covers and the format of server +responses. If you change to a different API version, the operations are not +guaranteed to be compatible and the server responses are not guaranteed to +be similar. -When you use the Versioned API feature with an official MongoDB driver, you +When you use the {+stable-api+} feature with an official MongoDB driver, you can update your driver or server without worrying about backward compatibility -issues of the commands covered by the Versioned API. +issues of the commands covered by the {+stable-api+}. -See the server manual page on the `Versioned API `__ +See the MongoDB reference page on the :manual:`{+stable-api+} ` for more information including a list of commands it covers. -The following sections describe how you can enable the Versioned API for +The following sections describe how you can enable the {+stable-api+} for your MongoDB client and the options that you can specify. -Enable the Versioned API on a MongoDB Client --------------------------------------------- +Enable the {+stable-api+} on a MongoDB Client +--------------------------------------------- -To enable the Versioned API, you must specify an API version in the ``MongoClientOptions`` +To enable the {+stable-api+}, you must specify an API version in the ``MongoClientOptions`` passed to your ``MongoClient``. Once you instantiate a ``MongoClient`` instance with a specified API version, all commands you run with that client use that -version of the Versioned API. +version of the {+stable-api+}. .. tip:: If you need to run commands using more than one version of the Versioned API, instantiate a separate client with that version. - If you need to run commands not covered by the Versioned API, make sure the + If you need to run commands not covered by the {+stable-api+}, make sure the "strict" option is disabled. See the section on - :ref:`Versioned API Options ` for more information. + :ref:`{+stable-api+} Options ` for more + information. The example below shows how you can instantiate a ``MongoClient`` that -sets the Versioned API version and connects to a server by performing the +sets the {+stable-api+} version and connects to a server by performing the following operations: - Specify a server URI to connect to. -- Specify a Versioned API version in the ``MongoClientOptions`` object, using a +- Specify a {+stable-api+} version in the ``MongoClientOptions`` object, using a constant from the ``ServerApiVersion`` object. - Instantiate a ``MongoClient``, passing the URI and the ``MongoClientOptions`` to the constructor. -.. literalinclude:: /code-snippets/versioned-api/basic.js +.. literalinclude:: /code-snippets/stable-api/basic.js :start-after: begin serverApiVersion :end-before: end serverApiVersion :language: javascript @@ -74,7 +78,7 @@ following operations: .. warning:: If you specify an API version and connect to a MongoDB server that does - not support the Versioned API, your application may throw an error when + not support the {+stable-api+}, your application may throw an error when connecting to your MongoDB server with the following text: .. code-block:: none @@ -89,12 +93,13 @@ section, see the following API Documentation: - `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ - `MongoClient <{+api+}/classes/MongoClient.html>`__ +.. _nodejs-stable-api-options: .. _versioned-api-options: -Versioned API Options ---------------------- +{+stable-api+} Options +---------------------- -You can enable or disable optional behavior related to the Versioned API as +You can enable or disable optional behavior related to the {+stable-api+} as described in the following table. .. list-table:: @@ -106,7 +111,7 @@ described in the following table. - Description * - version - - | **Required**. Specifies the version of the Versioned API. + - | **Required**. Specifies the version of the {+stable-api+}. | | Default: **null** @@ -125,7 +130,7 @@ described in the following table. The following example shows how you can set the options of the ``ServerApi`` interface. -.. literalinclude:: /code-snippets/versioned-api/options.js +.. literalinclude:: /code-snippets/stable-api/options.js :start-after: begin serverApiVersion :end-before: end serverApiVersion :language: javascript diff --git a/source/includes/fundamentals-sections.rst b/source/includes/fundamentals-sections.rst index aecdb0601..2c9ec5422 100644 --- a/source/includes/fundamentals-sections.rst +++ b/source/includes/fundamentals-sections.rst @@ -2,7 +2,7 @@ Learn how to perform the following tasks using the Node.js driver in the Fundamentals section: - :doc:`Connect to MongoDB ` -- :doc:`Use the Versioned API ` +- :doc:`Use the {+stable-api+} ` - :doc:`Authenticate with MongoDB ` - :doc:`Read from and Write to MongoDB ` - :doc:`Access Return Values ` @@ -13,6 +13,6 @@ Fundamentals section: - :doc:`Log Events in the Driver ` - :doc:`Monitor Driver Events ` - :doc:`Store and Retrieve Large Files in MongoDB ` -- :doc:`Create and Query Time Series Collection` +- :doc:`Create and Query Time Series Collection ` - :doc:`Specify Type Parameters with TypeScript `