|
| 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 | + |
0 commit comments