Skip to content

Commit 41b1a9a

Browse files
authored
DOCSP-37508 - Stable API (#46)
1 parent a449f04 commit 41b1a9a

File tree

3 files changed

+136
-0
lines changed

3 files changed

+136
-0
lines changed

source/connect/stable-api.txt

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
.. _pymongo-stable-api:
2+
3+
==============
4+
{+stable-api+}
5+
==============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: compatible, backwards, upgrade
19+
20+
.. note::
21+
22+
The {+stable-api+} feature requires MongoDB Server 5.0 or later.
23+
24+
Overview
25+
--------
26+
27+
In this guide, you can learn how to specify **{+stable-api+}** compatibility when
28+
connecting to a MongoDB deployment.
29+
30+
The {+stable-api+} feature forces the server to run operations with behaviors compatible
31+
with the API version you specify. When you update either your driver or server,
32+
the API version changes, which can change the way these operations behave.
33+
Using the {+stable-api+} ensures consistent responses from the server and
34+
provides long-term API stability for your application.
35+
36+
The following sections describe how you can enable and customize {+stable-api+} for
37+
your MongoDB client. For more information about the {+stable-api+}, including a list of
38+
the commands it supports, see :manual:`Stable API </reference/stable-api/>` in the
39+
MongoDB Server manual.
40+
41+
Enable the {+stable-api+}
42+
-------------------------
43+
44+
To enable the {+stable-api+}, perform the following steps:
45+
46+
1. Construct a ``ServerApi`` object and specify a {+stable-api+} version. You must use
47+
a {+stable-api+} version defined in the ``ServerApiVersion`` enum.
48+
#. Construct a ``MongoClient`` object, passing in your ``ServerApi`` object for the
49+
``server_api`` argument.
50+
51+
The following code example shows how to perform this process:
52+
53+
.. literalinclude:: /includes/connect/stable_api.py
54+
:start-after: # start stable api
55+
:end-before: # end stable api
56+
:language: python
57+
:dedent:
58+
59+
Once you create a ``MongoClient`` instance with
60+
a specified API version, all commands you run with the client use the specified
61+
version. If you need to run commands using more than one version of the
62+
{+stable-api+}, create a new ``MongoClient``.
63+
64+
.. _stable-api-options:
65+
66+
Configure the {+stable-api+}
67+
------------------------
68+
69+
The following table describes the parameters of the ``ServerApi`` class. You can use these
70+
parameters to customize the behavior of the {+stable-api+}.
71+
72+
.. list-table::
73+
:header-rows: 1
74+
:stub-columns: 1
75+
:widths: 25,75
76+
77+
* - Option Name
78+
- Description
79+
80+
* - strict
81+
- | **Optional**. When ``True``, if you call a command that isn't part of
82+
the declared API version, the driver raises an exception.
83+
|
84+
| Default: **False**
85+
86+
* - deprecation_errors
87+
- | **Optional**. When ``True``, if you call a command that is deprecated in the
88+
declared API version, the driver raises an exception.
89+
|
90+
| Default: **False**
91+
92+
The following code example shows how you can use these parameters when constructing a
93+
``ServerApi`` object:
94+
95+
.. literalinclude:: /includes/connect/stable_api.py
96+
:start-after: # start stable api options
97+
:end-before: # end stable api options
98+
:language: python
99+
:dedent:
100+
101+
Troubleshooting
102+
---------------
103+
104+
.. include:: /includes/troubleshooting/stable-api.rst
105+
106+
API Documentation
107+
-----------------
108+
109+
For more information about using the {+stable-api+} with {+driver-short+}, see the
110+
following API documentation:
111+
112+
- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__
113+
- `ServerApi <{+api-root+}pymongo/server_api.html#pymongo.server_api.ServerApi>`__
114+
- `ServerApiVersion <{+api-root+}pymongo/server_api.html#pymongo.server_api.ServerApiVersion>`__
115+

source/includes/connect/stable_api.py

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# start stable api
2+
3+
# end stable api
4+
5+
# start stable api options
6+
7+
# end stable api options
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Unrecognized field 'apiVersion' on server
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
{+driver-short+} raises this exception if you specify an API version and connect to a
5+
MongoDB server that doesn't support the {+stable-api+}. Ensure you're connecting to a
6+
deployment running MongoDB Server v5.0 or later.
7+
8+
Provided apiStrict:true, but the command count is not in API Version
9+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10+
11+
{+driver-short+} raises this exception if your ``MongoClient`` runs an operation that
12+
isn't in the {+stable-api+} version you specified. To avoid this error, use an alternative
13+
operation supported by the specified {+stable-api+} version, or set the ``strict``
14+
option to ``False`` when constructing your ``ServerApi`` object.

0 commit comments

Comments
 (0)