Stable API

On this page

Overview

Specify an API Version
Modify Behavior
Additional Information

Note

The Stable API feature requires MongoDB Server 5.0 or later.

Only use the Stable API feature 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 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 may 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 the server covers, see Stable API.

Specify an API Version

The Client optionally takes a ServerAPIOptions type through the ClientOptions.

To specify an API version, append the SetServerAPIOptions() method with your server API options to your ClientOptions. After you specify an API version, the Client runs operations that are compatible with the API version for the duration of your connection.

Note

The MongoDB Go Driver currently only supports ServerAPIVersion1.

Example

The following example instantiates a Client that sets the Stable API version and connects to a server.

// Specify a server URI to connect to
uri := "mongodb://<hostname>:<port>"
// Specify the Stable API version in the ClientOptions object
serverAPI := options.ServerAPI(options.ServerAPIVersion1)
// Pass in the URI and the ClientOptions to the Client
client, err := mongo.Connect(options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPI))
if err != nil {
    panic(err)
}

Modify Behavior

You can further modify the behavior of the stable API feature by appending to the ServerAPIOptions type. If you don't specify any options, the driver uses the default values for each option.

Method	Description
`ServerAPI()`	The API version to use. Default: ServerAPIVersion1
`SetStrict()`	Flag that indicates whether the server should return errors for features that aren't part of the API version. Default: false
`SetDeprecationErrors()`	Flag that indicates whether the server should return errors for deprecated features. Default: false

Example

This example specifies for the server to perform the following actions:

Use Version 1 of the API
Return errors for features that aren't part of Version 1
Return errors for deprecated features

// Specify a server URI to connect to
uri := "mongodb://<hostname>:<port>"
// Specify the Stable API version and append options in the ClientOptions object
serverAPI := options.ServerAPI(options.ServerAPIVersion1).SetStrict(true).SetDeprecationErrors(true)
// Pass in the URI and the ClientOptions to the Client
client, err := mongo.Connect(options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPI))
if err != nil {
    panic(err)
}

Additional Information

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

API Documentation

For more information on the options in this section, see the following API Documentation:

Back

Configure TLS

Context