diff --git a/source/reference/versioned-api.txt b/source/reference/versioned-api.txt index 5444de8de43..5ae5c60bfad 100644 --- a/source/reference/versioned-api.txt +++ b/source/reference/versioned-api.txt @@ -12,7 +12,7 @@ Versioned API What is the Versioned API, and Should You Use It? ------------------------------------------------- - + The MongoDB Versioned API lets you upgrade your MongoDB server at will, and ensure that behavior changes between MongoDB versions do not break your application. @@ -44,7 +44,7 @@ resulting from server upgrades. This guarantee holds as long as the new server supports your specified API version. To guarantee backward compatibility, your application must: - + - Declare an API version - Only use commands and features supported in your specified API version - Deploy with a supported version of an official driver @@ -52,28 +52,160 @@ To guarantee backward compatibility, your application must: Declare the API Version ----------------------- +---------- + +.. |arrow| unicode:: U+27A4 + +|arrow| Use the **Select your language** drop-down menu in the +upper-right to set the language of the examples on this page. + +---------- + To use the Versioned API, upgrade to the latest driver and create your application's MongoClient: -.. code-block:: none +.. tabs-selector:: drivers + +.. tabs-drivers:: + + .. tab:: + :tabid: shell - client = MongoClient( - , - api={"version": "1", "strict": True} - ) + .. code-block:: javascript + + mongosh --apiVersion 1 -Alternatively, if you are using :mongosh:`MongoDB Shell `, -you can specify the :option:`--apiStrict` and :option:`--apiVersion` -connection options: + .. tab:: + :tabid: python -.. code-block:: shell + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Versioned API Example 1 + :end-before: End Versioned API Example 1 - mongosh --apiVersion 1 --apiStrict + .. tab:: + :tabid: php + + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php + :language: php + :dedent: 8 + :start-after: Start Versioned API Example 1 + :end-before: End Versioned API Example 1 + + .. tab:: + :tabid: c + + .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c + :language: c + :dedent: 3 + :start-after: Start Versioned API Example 1 + :end-before: End Versioned API Example 1 + + .. tab:: + :tabid: go + + .. literalinclude:: /driver-examples/go_examples.go + :language: go + :dedent: 0 + :start-after: Start Versioned API Example 1 + :end-before: End Versioned API Example 1 + + .. tab:: + :tabid: csharp + + .. literalinclude:: /driver-examples/VersionedApiExamples.cs + :language: csharp + :dedent: 12 + :start-after: Start Versioned API Example 1 + :end-before: End Versioned API Example 1 + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /driver-examples/node_versioned_api.js + :language: nodejs + :dedent: 4 + :start-after: Start Versioned API Example 1 + :end-before: End Versioned API Example 1 ``"1"`` is currently the only API version available. -Setting ``{ "strict" : True }`` or :option:`--apiStrict` means the -server will reject all commands outside of the Versioned API. +By default, clients are *non-strict*. A non-strict client allows you +to run any command, regardless of whether or not it belongs to the +Versioned API. + +Create a Strict Client +---------------------- + +A *strict* client rejects all commands outside of the Versioned API. +Attempts to use commands outside of the Versioned API will receive the +:ref:`APIVersionError ` response. + +Use the sample code to create a *strict* client: + +.. tabs-drivers:: + + .. tab:: + :tabid: shell + + .. code-block:: javascript + + mongosh --apiVersion 1 --apiStrict + + .. tab:: + :tabid: python + + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Versioned API Example 2 + :end-before: End Versioned API Example 2 + + .. tab:: + :tabid: php + + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php + :language: php + :dedent: 8 + :start-after: Start Versioned API Example 2 + :end-before: End Versioned API Example 2 + + .. tab:: + :tabid: c + + .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c + :language: c + :dedent: 3 + :start-after: Start Versioned API Example 2 + :end-before: End Versioned API Example 2 + + .. tab:: + :tabid: go + + .. literalinclude:: /driver-examples/go_examples.go + :language: go + :dedent: 0 + :start-after: Start Versioned API Example 2 + :end-before: End Versioned API Example 2 + + .. tab:: + :tabid: csharp + + .. literalinclude:: /driver-examples/VersionedApiExamples.cs + :language: csharp + :dedent: 12 + :start-after: Start Versioned API Example 2 + :end-before: End Versioned API Example 2 + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /driver-examples/node_versioned_api.js + :language: nodejs + :dedent: 4 + :start-after: Start Versioned API Example 2 + :end-before: End Versioned API Example 2 Migrate To Versioned API Commands --------------------------------- @@ -135,7 +267,7 @@ However, the :dbcommand:`aggregate` command is obtain a count in the following way: .. code-block:: javascript - + db.sales.aggregate([ { $group: { @@ -157,23 +289,72 @@ How To Use Commands and Features Outside of the Versioned API To use commands and features outside of the Versioned API, you can connect to your deployment with a *non-strict* client. By default, -clients are *non-strict* unless specified otherwise in the connection. +clients are *non-strict*. + +Use the sample code to create a *non-strict* client: + +.. tabs-drivers:: + + .. tab:: + :tabid: shell -.. code-block:: none + .. code-block:: javascript + + mongosh --apiVersion 1 - # Non-strict client - client = MongoClient( - , - api={"version": "1", "strict": False} - ) + .. tab:: + :tabid: python -If you are running :mongosh:`mongosh `, you can create a -non-strict client by specifying :option:`--apiVersion` and omitting -the :option:`--apiStrict` option. + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Versioned API Example 3 + :end-before: End Versioned API Example 3 -.. code-block:: shell + .. tab:: + :tabid: php - mongosh --apiVersion 1 + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php + :language: php + :dedent: 8 + :start-after: Start Versioned API Example 3 + :end-before: End Versioned API Example 3 + + .. tab:: + :tabid: c + + .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c + :language: c + :dedent: 3 + :start-after: Start Versioned API Example 3 + :end-before: End Versioned API Example 3 + + .. tab:: + :tabid: go + + .. literalinclude:: /driver-examples/go_examples.go + :language: go + :dedent: 0 + :start-after: Start Versioned API Example 3 + :end-before: End Versioned API Example 3 + + .. tab:: + :tabid: csharp + + .. literalinclude:: /driver-examples/VersionedApiExamples.cs + :language: csharp + :dedent: 12 + :start-after: Start Versioned API Example 3 + :end-before: End Versioned API Example 3 + + .. tab:: + :tabid: nodejs + + .. literalinclude:: /driver-examples/node_versioned_api.js + :language: nodejs + :dedent: 4 + :start-after: Start Versioned API Example 3 + :end-before: End Versioned API Example 3 Using this non-strict client allows you to run commands outside of the Versioned API. For example, this non-strict client now allows you to