Stable API
Note
The Stable API feature requires MongoDB Server 5.0 or later.
Use the Stable API feature only if all the MongoDB servers you are connecting to support this feature.
Overview
In this guide, you can learn how to specify the Stable API when connecting to a MongoDB instance or replica set. You can use the Stable API feature to force the server to run operations with behavior compatible with the specified API version. An API version defines the expected behavior of the operations it covers and the format of server responses. If you change to a different API version, the operations are not guaranteed to be compatible and the server responses are not guaranteed to be similar.
When you use the Stable API feature with an official MongoDB driver, you can update your driver or server without worrying about backward compatibility issues of the commands covered by the Stable API.
See the MongoDB reference page on the Stable API for more information including a list of commands it covers.
The following sections describe how you can enable the Stable API for your MongoDB client and the options that you can specify.
Enable the Stable API on a MongoDB Client
To enable the Stable API, you must specify an API version in the MongoClientOptions
passed to your MongoClient
. Once you instantiate a MongoClient
instance with
a specified API version, all commands you run with that client use that
version of the Stable API.
Tip
- You must create a new client for each version of the Stable API on
- which you want to run a command.
To run commands that are not covered by the Stable API, make sure the "strict" option is disabled. See the section on Stable API Options for more information.
The example below shows how you can instantiate a MongoClient
that
sets the Stable API version and connects to a server by performing the
following operations:
Specify a server URI to connect to.
Specify a Stable API version in the
MongoClientOptions
object, using a constant from theServerApiVersion
object.Instantiate a
MongoClient
, passing the URI and theMongoClientOptions
to the constructor.
const { MongoClient, ServerApiVersion } = require("mongodb"); // Replace the placeholders in the connection string uri with your credentials const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority"; // Create a client with options to specify Stable API Version 1 const client = new MongoClient(uri, { serverApi: ServerApiVersion.v1 });
Warning
If you specify an API version and connect to a MongoDB Server that does not support the Stable API, your application may throw an error when connecting to your MongoDB Server with the following text:
MongoParseError: Invalid server API version=...
For more information on the methods and classes referenced in this section, see the following API Documentation:
Stable API Options
You can enable or disable optional behavior related to the Stable API as described in the following table.
Option Name | Description |
---|---|
version | Required. Specifies the version of the Stable API. Default: null |
strict | Optional. When set, if you call a command that is not part of the declared API version, the driver raises an exception. Default: false |
deprecationErrors | Optional. When set, if you call a command that is deprecated in the declared API version, the driver raises an exception. Default: false |
The following example shows how you can set the options of the ServerApi
interface.
const { MongoClient, ServerApiVersion } = require("mongodb"); // Replace the placeholders in the connection string uri with your credentials const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority"; /* Create a client with options to specify Stable API Version 1, return errors for commands outside of the API version, and raise exceptions for deprecated commands */ const client = new MongoClient(uri, { serverApi: { version: ServerApiVersion.v1, strict: true, deprecationErrors: true, } });
For more information on the options in this section, see the following API Documentation: