Stable API

On this page

Overview

Enable the Stable API
Configure the Stable API
API Documentation

Note

The Stable API feature requires MongoDB Server 5.0 or later.

Overview

In this guide, you can learn how to specify Stable API compatibility when connecting to a MongoDB deployment.

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 supports, see Stable API in the MongoDB Server manual.

Enable the Stable API

To enable the Stable API, perform the following steps:

Construct a mongocxx::options::server_api object and specify a Stable API version. You must use a Stable API version defined in the mongocxx::options::server_api::version enum. Currently, the driver supports only version 1 (k_version_1).
Construct a mongocxx::options::client object. Set the server_api_opts field of this object to the server_api object you created in the previous step.
Construct a mongocxx::client object, passing in your mongocxx::uri object and the mongocxx::options::client object you created in the previous step.

The following code example shows how to specify Stable API version 1:

#include <mongocxx/instance.hpp>
#include <mongocxx/uri.hpp>
#include <mongocxx/client.hpp>
int main()
{
    mongocxx::instance instance;
    mongocxx::uri uri("mongodb://<hostname>:<port>");
    mongocxx::options::server_api server_api_options(mongocxx::options::server_api::version::k_version_1);
    mongocxx::options::client client_options;
    client_options.server_api_opts(server_api_options);
    mongocxx::client client(uri, client_options);
}

Note

After you create a mongocxx::client instance with a specified API version, all commands you run with the client use the specified version. If you need to run commands using more than one version of the Stable API, create a new mongocxx::client instance.

Configure the Stable API

The following table describes the properties of the server_api_options class. You can use these properties to customize the behavior of the Stable API.

Option Name	Description
strict	Optional. When `true`, if you call a command that isn't part of the declared API version, the driver raises an exception. Default: `false`
deprecation_errors	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 code example shows how you can use these parameters when constructing a ServerApi object:

#include <mongocxx/instance.hpp>
#include <mongocxx/uri.hpp>
#include <mongocxx/client.hpp>
int main()
{
    mongocxx::instance instance;
    mongocxx::uri uri("mongodb://<hostname>:<port>");
    mongocxx::options::server_api server_api_options(mongocxx::options::server_api::version::k_version_1);
    server_api_options.strict(true);
    server_api_options.deprecation_errors(true);
    mongocxx::options::client client_options;
    client_options.server_api_opts(server_api_options);
    mongocxx::client client(uri, client_options);
}

API Documentation

For more information about using the Stable API with the C++ driver, see the following API documentation:

Back

Compress Network Traffic

Connection Pools