Docs Menu
Docs Home
/ / /
C Driver
/

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.

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.

To enable the Stable API, perform the following steps:

  1. Construct a mongoc_server_api_t object and specify a Stable API version. You must use a Stable API version defined in the mongoc_server_api_t enum.

  2. Construct a mongoc_client_t object.

  3. Pass the client and the Stable API object to the mongoc_client_set_server_api function.

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

#include <mongoc/mongoc.h>
int main ()
{
bson_error_t error;
mongoc_init ();
mongoc_server_api_t *stable_api = mongoc_server_api_new (MONGOC_SERVER_API_V1);
mongoc_client_t *client = mongoc_client_new ("<connection string>");
if (!mongoc_client_set_server_api (client, stable_api, &error))
{
fprintf (stderr, "Failed to set Stable API: %s\n", error.message);
return EXIT_FAILURE;
}
// Use the client for operations...
mongoc_server_api_destroy (stable_api);
mongoc_cleanup ();
return EXIT_SUCCESS;
}

Once you create a 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 client.

The following table describes the options of the ServerApi class. You can use these options 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 set both options to true when constructing a ServerApi object:

mongoc_server_api_t *stable_api = mongoc_server_api_new (MONGOC_SERVER_API_V1);
mongoc_server_api_strict (stable_api, true);
mongoc_server_api_deprecation_errors (stable_api, true);
mongoc_client_t *client = mongoc_client_new ("<connection string>");
if (!mongoc_client_set_server_api (client, stable_api, &error)) {
fprintf (stderr, "Failed to set Stable API: %s\n", error.message);
return EXIT_FAILURE;
}

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

Back

Create a MongoClient