/ /

Connect

Specify Connection Options

Specify Connection Options

Stable API

Note

The Stable API feature requires MongoDB 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. When you update either your driver or server, the API version changes, which can change the way these operations behave. 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 Stable API in the MongoDB Server manual.

Enable the Stable API

To enable the Stable API, perform the following steps:

Construct a ServerApi object and specify a Stable API version. You must use a Stable API version defined in the ServerApiVersion enum.
Construct a MongoClient object, passing in your ServerApi object for the server_api argument.

The following code example shows how to specify Stable API version 1. Select the Synchronous or Asynchronous tab to see the corresponding code:

from pymongo import MongoClient
from pymongo.server_api import ServerApi
client = MongoClient("mongodb://<db_username>:<db_password>@<hostname:<port>",
                     server_api=ServerApi("1"))

from pymongo import AsyncMongoClient
from pymongo.server_api import ServerApi
client = AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname:<port>",
                          server_api=ServerApi("1"))

Once you create a MongoClient instance with a specified API version, all commands you run with the client use the specified version. If you need to run commands using more than one version of the Stable API, create a new MongoClient.

Configure the Stable API

The following table describes the parameters of the ServerApi class. You can use these parameters to customize the behavior of the Stable API.

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 use these parameters when constructing a ServerApi object. Select the Synchronous or Asynchronous tab to see the corresponding code:

from pymongo import MongoClient
from pymongo.server_api import ServerApi
client = MongoClient("mongodb://<db_username>:<db_password>@<hostname:<port>",
                     server_api=ServerApi("1",
                     strict=True,
                     deprecation_errors=True))

from pymongo import AsyncMongoClient
from pymongo.server_api import ServerApi
client = AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname:<port>",
                          server_api=ServerApi("1",
                          strict=True,
                          deprecation_errors=True))

Troubleshooting

Unrecognized field 'apiVersion' on server

PyMongo 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 MongoDB Server v5.0 or later.

Provided apiStrict:true, but the command count is not in API Version

PyMongo raises this exception if your MongoClient 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 PyMongo, see the following API documentation:

Back

Customize Server Selection

Limit Server Execution Time