Stable API

On this page

What is the Stable API, and Should You Use It?

Backward Compatibility Guarantee
Declare the API Version
Checking Client API Versions
Create a Strict Client
Migrate To Stable API Commands
How To Use Commands and Features Outside of the Stable API
Stable API Commands
Parameters
Behavior
Stable API Error Responses

What is the Stable API, and Should You Use It?

The MongoDB Stable API (previously labeled the Versioned API) lets you upgrade your MongoDB server at will, and ensure that behavior changes between MongoDB versions do not break your application.

MongoDB 5.0 introduces the Stable API for applications communicating with MongoDB server products. The Stable API allows you to specify which version of the MongoDB API your application runs against.

The Stable API provides long-term API stability for applications and supports more frequent releases and automatic server upgrades. This allows your applications to take advantage of rapidly released features without risking backwards-breaking changes.

The default behavior for your driver connection will continue to function as expected, even if you do not explicitly specify an apiVersion.

The Stable API encompasses the subset of MongoDB commands that applications use to read and write data, create collections and indexes, and perform other common tasks.

Note

Starting in February 2022, the "Versioned API" terminology was changed to "Stable API". All concepts and features remain the same with this naming change.

Backward Compatibility Guarantee

Your application will not experience significant behavior changes resulting from server upgrades. This guarantee holds as long as the new server supports your specified API version.

To guarantee backward compatibility, your application must:

Declare an API version
Only use commands and features supported in your specified API version
Deploy with a supported version of an official driver

Declare the API Version

➤ Use the Select your language drop-down menu in the upper-right to set the language of the examples on this page.

To use the Stable API, upgrade to the latest driver and create your application's MongoClient:

mongosh --apiVersion 1

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")};
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPIExample is an example of creating a client with stable API.
func StableAPIExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .build()
                ).build()
        );
return client;

    from pymongo.server_api import ServerApi
    client = AsyncIOMotorClient(uri, server_api=ServerApi("1"))

client = new MongoClient(uri, { serverApi: { version: '1' } });

$serverApi = new \MongoDB\Driver\ServerApi('1');
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

from pymongo.server_api import ServerApi
MongoClient(uri, server_api=ServerApi("1"))

client = Mongo::Client.new(uri_string, server_api: {version: "1"})

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

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1)
    )
    let client = try MongoClient(uri, options: opts)

"1" is currently the only API version available.

By default, clients are non-strict. A non-strict client allows you to run any command, regardless of whether or not it belongs to the Stable API.

Checking Client API Versions

Use the serverStatus command to check for your application's configured API version. For each application connected to your MongoDB instance, an appname appears in the apiVersions document.

See metrics.apiVersions for more information.

db.runCommand( { serverStatus: 1 } ).metrics.apiVersions

Create a Strict Client

A strict client rejects all commands outside of the Stable API. Attempts to use commands outside of the Stable API will receive the APIVersionError response.

A strict client also ignores unsupported index types during query planning and execution.

Use the sample code to create a strict client:

mongosh --apiVersion 1 --apiStrict

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
mongoc_server_api_strict (server_api, true);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")}
        .strict(true);  // Enable strict mode for the server API
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version and options
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1, strict: true);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPIStrictExample is an example of creating a client with strict stable API.
func StableAPIStrictExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(true)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .strict(true)
                .build()
                ).build()
        );
return client;

    client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=True))

client = new MongoClient(uri, { serverApi: { version: '1', strict: true } });

$serverApi = new \MongoDB\Driver\ServerApi('1', true);
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

MongoClient(uri, server_api=ServerApi("1", strict=True))

client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: true})

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

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: true)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: true)
    )
    let client = try MongoClient(uri, options: opts)

Migrate To Stable API Commands

To migrate your application to use the Stable API, you must:

Run your application's test suite with the new MongoClient options.
Determine which commands and features you're using that are outside of the Stable API.
Migrate to alternative commands and features in the Stable API.

Once your application uses only commands and features defined in the Stable API, you can redeploy it with the new MongoClient options and be confident that future server upgrades won't negatively impact your application.

How To Use Commands and Features Outside of the Stable API

To use commands and features outside of the Stable API, you can connect to your deployment with a non-strict client. By default, clients are non-strict.

To create a non-strict client, use the following sample code:

mongosh --apiVersion 1

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
mongoc_server_api_strict (server_api, false);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")}
        .strict(false);  // Explicitly disable strict mode for the server API
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version and options
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1, strict: false);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPINonStrictExample is an example of creating a client with non-strict stable API.
func StableAPINonStrictExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(false)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .strict(false)
                .build()
                ).build()
        );

    client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=False))

client = new MongoClient(uri, { serverApi: { version: '1', strict: false } });

$serverApi = new \MongoDB\Driver\ServerApi('1', false);
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

MongoClient(uri, server_api=ServerApi("1", strict=False))

client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: false})

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

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: false)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: false)
    )
    let client = try MongoClient(uri, options: opts)

Using this non-strict client allows you to run commands outside of the Stable API. For example, this non-strict client allows you to run the createUser command.

Important

Commands and features outside of the Stable API do not have the same backward compatibility guarantees as versioned alternatives.

Stable API Commands

The database commands included in Stable API V1 depend on the MongoDB version you are using. To view the database commands included in the Stable API and the MongoDB version they were introduced, see Stable API Changelog.

Parameters

You can specify the following optional parameters for Stable API in your application's MongoDB driver connection code. Check the MongoDB driver documentation for the driver you use in your application for more information:

Parameter	Type	Description
apiVersion	string	Specifies the API Version. `"1"` is currently the only supported version.
apiStrict	boolean	If `true`: Using a command that is not part of the declared API version returns an APIStrictError error. Indexes that are unsupported by the Stable API are ignored by the query planner. If you specify apiStrict, you must also specify apiVersion. If not specified, defaults to `false`.
apiDeprecationErrors	boolean	If `true`, using a command or behavior that is deprecated in the specified API version returns an APIDeprecationError. If you specify apiDeprecationErrors, you must also specify apiVersion. If not specified, defaults to `false`.

Behavior

Parameter Validation

Starting in MongoDB 5.0, API V1 database commands raise an error if passed a parameter not explicitly accepted by the command.

Stable API Error Responses

This table shows error responses for problematic Stable API requests.

Server Response	Request
APIDeprecationError	Specifies `{ apiDeprecationErrors: true }` with API version `V` and uses a behavior deprecated in `V`.
APIStrictError	Specifies `{ apiStrict: true }` with API version `V`, but uses a behavior not in version `V`.
APIVersionError	Specifies an apiVersion that the server does not support.
InvalidOptions	Specifies `{ apiStrict: true }` or `{ apiDeprecationErrors: true }` but omits apiVersion.

Back

Server Sessions

Migrate to Later Version