Stable API
On this page
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 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)?; 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: