Skip to content

DOCSP-17366 These updates add driver examples to the Versioned API page #5537

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 12, 2021
Merged

DOCSP-17366 These updates add driver examples to the Versioned API page #5537

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
235 changes: 208 additions & 27 deletions source/reference/versioned-api.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -44,36 +44,168 @@ 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

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(
<connection string>,
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 <api-vers-resp>` 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
---------------------------------
Expand Down Expand Up @@ -135,7 +267,7 @@ However, the :dbcommand:`aggregate` command is
obtain a count in the following way:

.. code-block:: javascript

db.sales.aggregate([
{
$group: {
Expand All @@ -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(
<connection string>,
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
Expand Down