Stable API

On this page

Overview

Specify an API Version
API Version Specification Example
Modify Behavior
Stable API Options Example
Additional Information
API Documentation

Important

To use the Stable API feature, you must connect to a deployment running MongoDB Server version 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 Stable API compatibility when connecting to a MongoDB instance or replica set.

The Stable API feature forces the server to run operations with behaviors that are compatible with the API version you specify. An API version defines the expected behavior of the operations it covers and the format of server responses. The operations and the server responses might differ depending on the API version you specify.

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.

To learn more about the commands that the server covers, see Stable API in the Server manual.

Specify an API Version

To specify an API version, define a ServerApi struct and set the server_api field of your ClientOptions instance to this struct. The ServerApi struct contains the API version and options. To learn more about setting options, see the Modify Behavior section of this guide.

After you specify an API version, the client runs only operations that are compatible with that version.

Note

The MongoDB Rust Driver supports only Stable API version 1.

API Version Specification Example

The following example sets the Stable API version when instantiating a Client and connects to a server.

let mut client_options = ClientOptions::parse(uri).await?;
let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
client_options.server_api = Some(server_api);
let client = Client::with_options(client_options)?;

Modify Behavior

You can modify the behavior of the Stable API feature by setting fields in the ServerApi struct.

While you can set the fields in a ServerApi struct manually, you can use the builder design pattern to define the struct more efficiently.

Note

Setting Options

The Rust driver implements the Builder design pattern for the creation of some struct types, including the ServerApi struct. You can use each type's builder() method to construct an options instance by chaining option builder functions one at a time.

Field	Description
`version`	(Required) The Stable API version to use. Specified with the `ServerApiVersion` enum. The only accepted value is `V1`. Type: `ServerApiVersion`
`strict`	Indicates whether the server returns errors for features that aren't part of the API version. Type: `bool` Default: `false`
`deprecation_errors`	Indicates whether the server returns errors for deprecated features. Type: `bool` Default: `false`

Stable API Options Example

This example enables the Stable API feature with the following specifications:

Uses Stable API version 1
Returns errors for features that aren't part of version 1
Returns errors for deprecated features

let mut client_options = ClientOptions::parse(uri).await?;
let server_api = ServerApi::builder()
    .version(ServerApiVersion::V1)
    .strict(true)
    .deprecation_errors(true)
    .build();
client_options.server_api = Some(server_api);
let client = Client::with_options(client_options)?;

Additional Information

To learn more about connecting to your MongoDB instance or replica set, see the Connection Guide.

API Documentation

To learn more about the methods and types mentioned in this guide, see the following API documentation:

Back

Enable & Configure TLS

Authentication