DOCSP-41125 Stable API

snooty.toml

@@ -11,6 +11,7 @@ toc_landing_pages = [
     "/read",
     "/connect",
     "/indexes",
+    "/connect",
     "work-with-indexes",
     "/data-formats"
 ]
@@ -28,5 +29,5 @@ mdb-server = "MongoDB Server"
 stable-api = "Stable API"
 api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
 java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}"
-core-api = "{+java-api+}/apidocs/mongodb-driver-core/"
 kotlin-docs = "https://kotlinlang.org"
+core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/com/mongodb"

source/connect.txt

@@ -18,17 +18,18 @@ Connect to MongoDB
    :description: Learn how to use the Kotlin Sync driver to connect to MongoDB.
    :keywords: client, ssl, tls, localhost
 
-.. .. toctree::
-..    :titlesonly:
-..    :maxdepth: 1
+.. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    /connect/stable-api
 .. 
 ..    /connect/mongoclient
 ..    /connect/connection-targets
 ..    /connect/connection-options
 ..    /connect/tls
 ..    /connect/network-compression
 ..    /connect/server-selection
-..    /connect/stable-api
 ..    /connect/csot
 
 Overview

source/connect/stable-api.txt

@@ -0,0 +1,136 @@
+.. _kotlin-sync-stable-api:
+
+==============
+{+stable-api+}
+==============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: compatible, backwards, upgrade
+
+.. note::
+
+   The {+stable-api+} feature requires {+mdb-server+} 5.0 or later.
+
+Overview
+--------
+
+In this guide, you can learn how to specify **{+stable-api+}** compatibility when 
+connecting to a MongoDB deployment.
+
+The {+stable-api+} feature forces the server to run operations with behaviors compatible 
+with the API version you specify. When you update either your driver or server, 
+the API version changes, which can change the way these operations behave.
+Using the {+stable-api+} ensures consistent responses from the server and 
+provides long-term API stability for your application.
+
+The following sections describe how you can enable and customize {+stable-api+} for
+your MongoDB client. For more information about the {+stable-api+}, including a list of 
+the commands it supports, see :manual:`Stable API </reference/stable-api/>` in the
+{+mdb-server+} manual.
+
+Enable the {+stable-api+}
+-------------------------
+
+To enable the {+stable-api+}, perform the following steps:
+
+1. Construct a ``ServerApi`` object and specify a {+stable-api+} version. You must use
+   a {+stable-api+} version defined in the ``ServerApiVersion`` enum.
+#. Construct a ``MongoClientSettings`` object using the ``MongoClientSettings.Builder`` class.
+#. Instantiate a ``MongoClient`` using the ``MongoClient.create()`` method and 
+   pass your ``MongoClientSettings`` instance as a parameter.
+
+The following code example shows how to specify {+stable-api+} version 1:
+
+.. literalinclude:: /includes/connect/stable-api.kt
+   :start-after: start-enable-stable-api
+   :end-before: end-enable-stable-api
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+Once you create a ``MongoClient`` instance with
+a specified API version, all commands you run with the client use the specified
+version. If you must run commands using more than one version of the 
+{+stable-api+}, create a new ``MongoClient``.
+
+.. _stable-api-options:
+
+Configure the {+stable-api+}
+----------------------------
+
+The following table describes the parameters of the ``ServerApi`` class. You can use these
+parameters to customize the behavior of the {+stable-api+}.
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 25,75
+
+   * - Option Name
+     - Description
+
+   * - strict
+     - | **Optional**. When ``True``, if you call a command that isn't part of 
+         the declared API version, the driver raises an exception.
+       |
+       | Default: **False**
+
+   * -  deprecationErrors
+     - | **Optional**. When ``True``, if you call a command that is deprecated in the 
+         declared API version, the driver raises an exception.
+       |
+       | Default: **False**
+
+The following code example shows how you can set the two options on an instance of ``ServerApi``
+by chaining methods on the ``ServerApi.Builder``:
+
+.. literalinclude:: /includes/connect/stable-api-options.kt
+   :start-after: start-stable-api-options
+   :end-before: end-stable-api-options
+   :language: kotlin
+   :copyable:
+   :dedent:
+
+Troubleshooting
+---------------
+
+Unrecognized field 'apiVersion' on server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} raises this exception if you specify an API version and connect to a
+MongoDB server that doesn't support the {+stable-api+}. Ensure you're connecting to a
+deployment running {+mdb-server+} v5.0 or later.
+
+Provided apiStrict:true, but the command count is not in API Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} raises this exception if your ``MongoClient`` runs an operation that
+isn't in the {+stable-api+} version you specified. To avoid this error, use an alternative
+operation supported by the specified {+stable-api+} version, or set the ``strict``
+option to ``False`` when constructing your ``ServerApi`` object.
+
+API Documentation
+-----------------
+
+For more information about using the {+stable-api+} with {+driver-short+}, see the 
+following API documentation: 
+
+- `ServerApi <{+core-api+}/ServerApi.html>`__
+- `ServerApi.Builder <{+core-api+}/ServerApi.Builder.html>`__
+- `ServerApiVersion <{+core-api+}/ServerApiVersion.html>`__
+- `ServerAddress <{+core-api+}/ServerAddress.html>`__
+- `MongoClientSettings <{+core-api+}/MongoClientSettings.html>`__
+- `MongoClientSettings.Builder <{+core-api+}/MongoClientSettings.Builder.html>`__
+- `MongoClient <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/index.html>`__
+- `MongoClient.create() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-client/-factory/create.html>`__
+

source/includes/connect/stable-api-options.kt

@@ -0,0 +1,16 @@
+import com.mongodb.ConnectionString
+import com.mongodb.MongoClientSettings
+import com.mongodb.client.model.*
+import com.mongodb.kotlin.client.*
+import org.bson.Document
+
+fun main() {
+
+    // start-stable-api-options
+    val serverApi = ServerApi.builder()
+        .version(ServerApiVersion.V1)
+        .strict(true)
+        .deprecationErrors(true)
+        .build()
+    // end-stable-api-options
+}

source/includes/connect/stable-api.kt

@@ -0,0 +1,31 @@
+import com.mongodb.ConnectionString
+import com.mongodb.MongoClientSettings
+import com.mongodb.client.model.*
+import com.mongodb.kotlin.client.*
+import org.bson.Document
+
+fun main() {
+
+    // start-enable-stable-api
+    val serverApi = ServerApi.builder()
+        .version(ServerApiVersion.V1)
+        .build()
+
+    // Replace the uri string placeholder with your MongoDB deployment's connection string
+    val uri = "<connection string>"
+
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString(ConnectionString(uri))
+        .serverApi(serverApi)
+        .build()
+
+    val client = MongoClient.create(settings)
+    // end-enable-stable-api
+
+    val serverApi = ServerApi.builder()
+    .version(ServerApiVersion.V1)
+    .strict(true)
+    .deprecationErrors(true)
+    .build()
+
+}