From 3f94a5e7a32525f73e70deaaeea816a8eac17653 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 8 Jan 2025 14:12:03 -0500 Subject: [PATCH 1/3] DOCSP-45181: Stable API --- source/connect.txt | 3 +- source/connect/stable-api.txt | 114 ++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 source/connect/stable-api.txt diff --git a/source/connect.txt b/source/connect.txt index 3e14a868..f3b875c7 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -22,4 +22,5 @@ Connect to MongoDB :titlesonly: :maxdepth: 1 - /connect/mongoclient \ No newline at end of file + /connect/mongoclient + /connect/stable-api \ No newline at end of file diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt new file mode 100644 index 00000000..bc138663 --- /dev/null +++ b/source/connect/stable-api.txt @@ -0,0 +1,114 @@ +.. _ruby-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. 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 ` in the +{+mdb-server+} manual. + +Enable the {+stable-api+} +------------------------- + +To enable the {+stable-api+}, pass a hash that specifies the {+stable-api+} version to the optional +``server_api`` parameter when you create a ``Mongo::Client`` instance. + +The following code example shows how to specify {+stable-api+} version 1: + +.. code-block:: ruby + + client = Mongo::Client.new(uri, server_api: { version: '1' }) + +Once you create a ``Client`` instance with +a specified API version, all commands that 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 ``Client``. + +Configure the {+stable-api+} +---------------------------- + +The following table describes {+stable-api+} options that you can set by specifying +them in the ``server_api`` hash. You can use these options 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** + + * - deprecation_errors + - | **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 a ``ServerApi`` instance: + +.. code-block:: ruby + + client = Mongo::Client.new(uri, + server_api: { version: '1', strict: true, deprecation_errors: true }) + +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 ``Client`` 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 the {+driver-short+}, see the +following API documentation: + +- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ \ No newline at end of file From 99f5ebac542704911bed445e60287e8ccf87ee87 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 8 Jan 2025 14:17:36 -0500 Subject: [PATCH 2/3] Fix --- source/connect/stable-api.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt index bc138663..c6a88611 100644 --- a/source/connect/stable-api.txt +++ b/source/connect/stable-api.txt @@ -85,7 +85,7 @@ The following code example shows how you can set the two options on a ``ServerAp .. code-block:: ruby client = Mongo::Client.new(uri, - server_api: { version: '1', strict: true, deprecation_errors: true }) + server_api: { version: '1', strict: true, deprecation_errors: true }) Troubleshooting --------------- From 448ee7dffd8f216d55d8553712845b54dbd75579 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 9 Jan 2025 09:05:51 -0500 Subject: [PATCH 3/3] LM feedback --- source/connect/stable-api.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt index c6a88611..b400aeb5 100644 --- a/source/connect/stable-api.txt +++ b/source/connect/stable-api.txt @@ -31,7 +31,7 @@ The {+stable-api+} feature forces the server to run operations with behaviors co with the API version you specify. 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 +The following sections describe how you can enable and customize the {+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 ` in the {+mdb-server+} manual. @@ -90,6 +90,8 @@ The following code example shows how you can set the two options on a ``ServerAp Troubleshooting --------------- +The following sections describe common issues you might encounter when using the {+stable-api+}. + Unrecognized field 'apiVersion' on server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~