Stable API

On this page

Overview

Enable the Stable API on a MongoDB Client
Stable API Options

Note

The Stable API feature requires MongoDB Server 5.0 or later.

You should only use the Stable API feature 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 settings of your MongoDB client. 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

To run commands that use more than one version of the Stable API, instantiate a separate client with that version.

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 that sets the Stable API version and connects to a server by performing the following operations:

Construct a ServerApi instance using the ServerApi.Builder helper class.
Specify a Stable API version using a constant from the ServerApiVersion class.
Construct a MongoClientSettings instance using the MongoClientSettings.Builder class.
Specify a server to connect to using a ServerAddress instance.
Instantiate a MongoClient using the MongoClients.create() method and pass your MongoClientSettings instance as a parameter.

ServerApi serverApi = ServerApi.builder()
        .version(ServerApiVersion.V1)
        .build();
// Replace the uri string with your MongoDB deployment's connection string
String uri = "<connection string uri>";
MongoClientSettings settings = MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(uri))
        .serverApi(serverApi)
        .build();
MongoClient client = MongoClients.create(settings);

Warning

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

'Unrecognized field 'apiVersion' on server...

For more information about 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
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 two options on an instance of ServerApi by chaining methods on the ServerApi.Builder:

ServerApi serverApi = ServerApi.builder()
        .version(ServerApiVersion.V1)
        .strict(true)
        .deprecationErrors(true)
        .build();

For more information about the options in this section, see the following API Documentation:

Back

Enterprise Authentication Mechanisms

Databases and Collections