DOCSP-20585: versioned API renamed to stable API (#200)

* DOCSP-20585: versioned API renamed to stable API

Author: Chris Cho

config/redirects

@@ -4,3 +4,5 @@ define: versions v4.3 v4.4 master
 
 raw: ${prefix}/ -> ${base}/current/
 raw: ${prefix}/master -> ${base}/upcoming/
+
+[*-master]: ${prefix}/${version}/fundamentals/versioned-api/ -> ${prefix}/${version}/fundamentals/stable-api/

snooty.toml

@@ -12,3 +12,4 @@ version = "4.4"
 full-version = "{+version+}.1"
 package-name-org = "mongodb-org"
 api = "https://mongodb.github.io/mongo-java-driver/{+version+}"
+stable-api = "Stable API"

source/fundamentals.txt

@@ -11,7 +11,7 @@ Fundamentals
    /fundamentals/connection
    /fundamentals/auth
    /fundamentals/enterprise-auth
-   /fundamentals/versioned-api
+   /fundamentals/stable-api
    /fundamentals/databases-collections
    /fundamentals/data-formats
    /fundamentals/crud

source/fundamentals/connection/mongoclientsettings.txt

@@ -123,7 +123,7 @@ connection behavior:
        if a network error occurs.
 
    * - ``serverApi()``
-     - Sets the :ref:`server API <versioned-api-java>` to use when sending
+     - Sets the :ref:`server API <stable-api-java>` to use when sending
        commands to the server.
 
    * - ``streamFactoryFactory()``

source/fundamentals/versioned-api.txt renamed to source/fundamentals/stable-api.txt

@@ -1,6 +1,9 @@
-=============
-Versioned API
-=============
+.. _versioned-api-java:
+.. _stable-api-java:
+
+==============
+{+stable-api+}
+==============
 
 .. default-domain:: mongodb
 
@@ -10,68 +13,66 @@ Versioned API
    :depth: 1
    :class: singlecol
 
-.. _versioned-api-java:
-
 .. 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
+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 <https://docs.mongodb.com/v5.0/reference/versioned-api/>`__
+See the MongoDB reference page on the :manual:`{+stable-api+} </reference/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 settings
+To enable the {+stable-api+}, you must specify an API version in the settings
 of your MongoDB client. 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 using more than one version of the 
+   {+stable-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 <versioned-api-options>` for more information.
+   :ref:`{+stable-api+} Options <stable-api-options>` for more information.
 
 The following example 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:
 
 - Construct a ``ServerApi`` instance using the ``ServerApi.Builder``
   helper class.
-- Specify a Versioned API version using a constant from the
+- Specify a {+stable-api+} version using a constant from the
   ``ServerApiVersion`` class.
 - Construct a ``MongoClientSettings`` instance using the
   ``MongoClientSettings.Builder`` class.
 - Specify a server to connect to using a ``ServerAddress`` instance.
 - Instantiate a ``MongoClient`` using the ``MongoClients.create()`` method
   and pass your ``MongoClientSettings`` instance as a parameter.
 
-.. literalinclude:: /includes/fundamentals/code-snippets/VersionedApiExample.java
+.. literalinclude:: /includes/fundamentals/code-snippets/StableApiExample.java
    :start-after: start serverAPIVersion
    :end-before: end serverAPIVersion
    :language: java
@@ -80,7 +81,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 raise an exception when
+   not support the {+stable-api+}, your application may raise an exception when
    executing a command on your MongoDB server. If you use a ``MongoClient``
    that specifies the API version to query a server that does not support it,
    your query could fail with an exception message that includes the
@@ -104,11 +105,12 @@ section, see the following API Documentation:
 - `MongoClient <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html>`__
 
 .. _versioned-api-options:
+.. _stable-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::
@@ -132,7 +134,7 @@ described in the following table.
 The following example shows how you can set the two options on an instance
 of ``ServerApi`` by chaining methods on the ``ServerApi.Builder``:
 
-.. literalinclude:: /includes/fundamentals/code-snippets/VersionedApiExample.java
+.. literalinclude:: /includes/fundamentals/code-snippets/StableApiExample.java
    :start-after: start apiVersionOptions
    :end-before: end apiVersionOptions
    :language: java

source/includes/fundamentals-sections.rst

@@ -2,7 +2,7 @@ Learn how to perform the following tasks using the Java driver in the
 Fundamentals section:
 
 - :doc:`Connect to MongoDB </fundamentals/connection>`
-- :doc:`Use the Versioned API </fundamentals/versioned-api>`
+- :doc:`Use the Stable API </fundamentals/stable-api>`
 - :doc:`Authenticate with MongoDB </fundamentals/auth>`
 - :doc:`Convert between MongoDB Data Formats and Java Objects </fundamentals/data-formats>`
 - :doc:`Read from and Write to MongoDB </fundamentals/crud>`

source/includes/fundamentals/code-snippets/StableApiExample.java

@@ -0,0 +1,39 @@
+package fundamentals;
+
+import com.mongodb.ConnectionString;
+import com.mongodb.MongoClientSettings;
+import com.mongodb.ServerApi;
+import com.mongodb.ServerApiVersion;
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+
+public class StableApiExample {
+    private static void setApiVersionOptions(String uri) {
+        // start apiVersionOptions
+        ServerApi serverApi = ServerApi.builder()
+                .version(ServerApiVersion.V1)
+                .strict(true)
+                .deprecationErrors(true)
+                .build();
+        // end apiVersionOptions
+    }
+
+    public static void main(String[] args) {
+        // start serverAPIVersion
+        ServerApi serverApi = ServerApi.builder()
+                .version(ServerApiVersion.V1)
+                .build();
+
+        // Replace the uri string with your MongoDB deployment's connection string
+        String uri = "<connection string uri>";
+
+        MongoClientSettings settings = MongoClientSettings.builder()
+                .applyConnectionString(new ConnectionString(uri))
+                .serverApi(serverApi)
+                .build();
+
+        MongoClient client = MongoClients.create(settings);
+        // end serverAPIVersion
+    }
+}
+

source/includes/fundamentals/code-snippets/VersionedApiExample.java

@@ -7,7 +7,7 @@
 import com.mongodb.client.MongoClient;
 import com.mongodb.client.MongoClients;
 
-public class VersionedApiExample {
+public class StableApiExample {
     private static void setApiVersionOptions(String uri) {
         // start apiVersionOptions
         ServerApi serverApi = ServerApi.builder()
@@ -24,7 +24,7 @@ public static void main(String[] args) {
                 .version(ServerApiVersion.V1)
                 .build();
 
-        // Replace the uri string with your MongoDB deployment's connection string
+        // Replace the placeholder with your MongoDB deployment's connection string uri
         String uri = "<connection string uri>";
 
         MongoClientSettings settings = MongoClientSettings.builder()

source/whats-new.txt

@@ -38,8 +38,14 @@ What's New in 4.3
 
 New features of the 4.3 Java driver release include:
 
-- Added support for MongoDB Versioned API. For more information, see our
-  :doc:`Versioned API guide </fundamentals/versioned-api>`.
+- Added support for the MongoDB {+stable-api+}. For more information, see our
+  :ref:`{+stable-api+} guide <stable-api-java>`.
+
+  .. note::
+
+     Starting from Feburary 2022, the **Versioned API** is known the **{+stable-api+}**.
+     All concepts and features remain the same with this naming change.
+
 - Added support for connection to
   `MongoDB Atlas Serverless Instances <https://www.mongodb.com/cloud/atlas/serverless>`__.
   For more information on setup, see our documentation on how to