Stable API

On this page

Overview

Enable the Stable API on a MongoDB Client
Stable API Options
API Documentation

Note

The Stable API feature requires MongoDB Server 5.0 or later.

You should use the Stable API feature only if all of the MongoDB servers you're connecting to support this feature.

Overview

In this guide, you can learn how to specify Stable API compatibility when connecting to a MongoDB instance or replica set.

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 covers, see the MongoDB reference page.

Enable the Stable API on a MongoDB Client

To enable the Stable API, you must specify an API version in the settings of your MongoDB client. Once you instantiate a MongoClient instance with a specified API version, all commands you run with the client use that version of the Stable API.

Tip

Once you've created a MongoClient, you can't change its Stable API version. If you need to run commands using more than one version of the Stable API, instantiate a separate client with that version.

If you need to run commands not covered by the Stable API, make sure the "strict" option is disabled. See the section on Stable API Options for more information.

The following example shows how you can instantiate a MongoClient with a Stable API version and connect to a server through the following operations:

Construct a ServerApi instance and specify a Stable API version.
Construct a MongoClientSettings object and set the ServerApi property.
Create a MongoClient with the MongoClientSettings object.

var serverApi = new ServerApi(ServerApiVersion.V1);
var settings = new MongoClientSettings { ServerApi = serverApi };
var client = new MongoClient(settings);

Warning

If you specify an API version and connect to a MongoDB server that does not support the Stable API, your code might raise an exception when executing a command on your MongoDB server. If you use a MongoClient that specifies the API version to query a server that doesn't support that version, your query could fail with an exception message that includes the following text:

Unrecognized field 'apiVersion' on server...

Stable API Options

You can use the options in the following table to customize the behavior of the Stable API.

Option Name	Description
Strict	Optional. When `true`, if you call a command that is not part of the declared API version, the driver raises an exception. Default: false
DeprecationErrors	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 example shows how you can set these options when constructing a ServerApi object:

var serverApi = new ServerApi(ServerApiVersion.V1, strict: true,
    deprecationErrors: true);

API Documentation

For more information on using the Stable API with the MongoDB .NET/C# Driver, see the following API documentation:

Back

Atlas Search

Authentication Mechanisms